From 91e0ffddf8326ba6fdf4780c63a47100905b0661 Mon Sep 17 00:00:00 2001 From: Agnieszka Besz Date: Fri, 15 Nov 2024 16:01:38 +0000 Subject: [PATCH 1/4] docs: ADR draft for introducing the deprecated State for ADRs --- content/ADR-253-introduce-depracated-state.md | 68 +++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 content/ADR-253-introduce-depracated-state.md diff --git a/content/ADR-253-introduce-depracated-state.md b/content/ADR-253-introduce-depracated-state.md new file mode 100644 index 00000000..09847c39 --- /dev/null +++ b/content/ADR-253-introduce-depracated-state.md @@ -0,0 +1,68 @@ +--- +layout: adr +adr: 253 # replace this number for the PR or ISSUE number +title: Introducing the "Deprecated" State for ADRs +date: 2024-11-15 +status: Draft # pick one of these +type: Meta +spdx-license: CC0-1.0 +authors: + - aixaCode # this is your github username +--- + +## Abstract + +This ADR proposes introducing a new **"Deprecated"** status for ADRs that are no longer relevant due to changes in Decentraland’s architecture, clients, or feature set. The goal is to improve clarity by distinguishing between ADRs that were once implemented and valid but are now outdated, versus those that were never accepted or implemented. + +## Context, Reach & Prioritization + +Currently, the available status options include "Withdrawn" and "Stagnant." However, these do not effectively communicate the state of ADRs that were once implemented but have since become obsolete due to changes in technology or product strategy. + +The **Withdrawn** status implies that an ADR was abandoned or deemed incorrect before implementation, while **Stagnant** is used for ADRs that were never finalized or have been inactive for too long. Neither status accurately reflects the state of ADRs that were previously accepted and implemented but are now outdated. + +Introducing a **"Deprecated"** status will: + +- Clearly identify ADRs that have been rendered obsolete due to changes in architecture or feature sets. +- Preserve the historical context of past decisions while indicating that they are no longer applicable. +- Reduce confusion among developers and stakeholders regarding the current relevance of ADRs. + +## Solution Space Exploration + +**Option 1**: Continue using the existing "Withdrawn" and "Stagnant" statuses with added explanations. +- **Pros**: No change to the current workflow. +- **Cons**: Does not address the confusion between ADRs that were valid but are now outdated versus those that were never fully accepted. + +**Option 2**: Introduce a new **"Deprecated"** status (proposed solution). +- **Pros**: Provides clear differentiation between ADRs that were previously implemented and those that were abandoned. Enhances clarity in documentation. +- **Cons**: Requires updating existing ADRs and adding a new status to the lifecycle. + +**Chosen Solution**: Introduce a new **"Deprecated"** status for ADRs that are no longer relevant but were once actively used and implemented. + +## Specification + +### Updated ADR States + +The full list of ADR states will now include: + +- **Idea**: An idea that is pre-draft, not tracked in the ADR repository. +- **Draft**: The first formally tracked stage of an ADR in development. +- **Review**: The ADR is ready for peer review. +- **Last Call**: Final review window before the ADR is marked as Final. +- **Final**: The ADR is accepted as a standard and is in use. +- **Stagnant**: ADRs that are inactive for over 6 months in Draft, Review, or Last Call. +- **Withdrawn**: The ADR was abandoned or rejected and will not be pursued further. +- **Living**: The ADR is designed to be continually updated and does not reach finality (e.g., ADR-1). +- **Deprecated**: The ADR was once Final and implemented but is now outdated or no longer relevant due to architectural changes. + +## Deprecated State Requirements + +- An ADR marked as **Deprecated** MUST include a **Deprecation Reason** section explaining why it is no longer relevant. +- If applicable, it should provide links to newer ADRs that supersede it. + +### Example Deprecation Notice +```markdown +**Notice**: This ADR has been marked as **Deprecated** as of 2024-11-15 due to the deprecation of the old Decentraland client. Refer to [ADR-123: Updated Client Architecture](/adr/ADR-123) for more information. + +## RFC 2119 and RFC 8174 + +> The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174. From 55f48567ef7ec242d7a81c9d10ed9dcd4e27742d Mon Sep 17 00:00:00 2001 From: Aga Date: Mon, 18 Nov 2024 17:22:50 +0000 Subject: [PATCH 2/4] Updated the formating Signed-off-by: Aga --- content/ADR-253-introduce-depracated-state.md | 59 ++++++++++++------- 1 file changed, 39 insertions(+), 20 deletions(-) diff --git a/content/ADR-253-introduce-depracated-state.md b/content/ADR-253-introduce-depracated-state.md index 09847c39..7dab20d7 100644 --- a/content/ADR-253-introduce-depracated-state.md +++ b/content/ADR-253-introduce-depracated-state.md @@ -1,26 +1,26 @@ --- -layout: adr -adr: 253 # replace this number for the PR or ISSUE number -title: Introducing the "Deprecated" State for ADRs -date: 2024-11-15 -status: Draft # pick one of these -type: Meta -spdx-license: CC0-1.0 -authors: - - aixaCode # this is your github username +layout: adr +adr: 253 # replace this number with the PR or ISSUE number +title: Introducing the "Deprecated" State for ADRs +date: 2024-11-15 +status: Draft +type: Meta +spdx-license: CC0-1.0 +authors: + - aixaCode --- ## Abstract -This ADR proposes introducing a new **"Deprecated"** status for ADRs that are no longer relevant due to changes in Decentraland’s architecture, clients, or feature set. The goal is to improve clarity by distinguishing between ADRs that were once implemented and valid but are now outdated, versus those that were never accepted or implemented. +This ADR proposes introducing a new **Deprecated** status for ADRs that are no longer relevant due to changes in Decentraland’s architecture, clients, or feature set. The goal is to improve clarity by distinguishing between ADRs that were once implemented and valid but are now outdated, versus those that were never accepted or implemented. ## Context, Reach & Prioritization -Currently, the available status options include "Withdrawn" and "Stagnant." However, these do not effectively communicate the state of ADRs that were once implemented but have since become obsolete due to changes in technology or product strategy. +Currently, the available status options include **Withdrawn** and **Stagnant**. However, these do not effectively communicate the state of ADRs that were once implemented but have since become obsolete due to changes in technology or product strategy. The **Withdrawn** status implies that an ADR was abandoned or deemed incorrect before implementation, while **Stagnant** is used for ADRs that were never finalized or have been inactive for too long. Neither status accurately reflects the state of ADRs that were previously accepted and implemented but are now outdated. -Introducing a **"Deprecated"** status will: +Introducing a **Deprecated** status will: - Clearly identify ADRs that have been rendered obsolete due to changes in architecture or feature sets. - Preserve the historical context of past decisions while indicating that they are no longer applicable. @@ -28,20 +28,42 @@ Introducing a **"Deprecated"** status will: ## Solution Space Exploration -**Option 1**: Continue using the existing "Withdrawn" and "Stagnant" statuses with added explanations. +### Option 1: Continue Using the Existing Statuses - **Pros**: No change to the current workflow. - **Cons**: Does not address the confusion between ADRs that were valid but are now outdated versus those that were never fully accepted. -**Option 2**: Introduce a new **"Deprecated"** status (proposed solution). +### Option 2: Introduce a New **Deprecated** Status (Chosen Solution) - **Pros**: Provides clear differentiation between ADRs that were previously implemented and those that were abandoned. Enhances clarity in documentation. - **Cons**: Requires updating existing ADRs and adding a new status to the lifecycle. -**Chosen Solution**: Introduce a new **"Deprecated"** status for ADRs that are no longer relevant but were once actively used and implemented. +### Chosen Solution + +Introduce a new **Deprecated** status for ADRs that are no longer relevant but were once actively used and implemented. ## Specification ### Updated ADR States +```mermaid +flowchart TB + Draft --> Withdrawn + Idea --> Draft + + Draft --> Review + Review <--> Living + Review <--> LastCall + LastCall --> Final + + Review --> Withdrawn + LastCall --> Withdrawn + + LastCall <--> Stagnant + Review <--> Stagnant + Draft <--> Stagnant + + Final --> Deprecated +``` + The full list of ADR states will now include: - **Idea**: An idea that is pre-draft, not tracked in the ADR repository. @@ -54,15 +76,12 @@ The full list of ADR states will now include: - **Living**: The ADR is designed to be continually updated and does not reach finality (e.g., ADR-1). - **Deprecated**: The ADR was once Final and implemented but is now outdated or no longer relevant due to architectural changes. -## Deprecated State Requirements +### Deprecated State Requirements - An ADR marked as **Deprecated** MUST include a **Deprecation Reason** section explaining why it is no longer relevant. - If applicable, it should provide links to newer ADRs that supersede it. ### Example Deprecation Notice + ```markdown **Notice**: This ADR has been marked as **Deprecated** as of 2024-11-15 due to the deprecation of the old Decentraland client. Refer to [ADR-123: Updated Client Architecture](/adr/ADR-123) for more information. - -## RFC 2119 and RFC 8174 - -> The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174. From b5c526a3cf283bf51e6ba00d0b864b150d0517a8 Mon Sep 17 00:00:00 2001 From: Aga Date: Tue, 26 Nov 2024 16:04:56 +0000 Subject: [PATCH 3/4] Update ADR-253-introduce-depracated-state.md Signed-off-by: Aga --- content/ADR-253-introduce-depracated-state.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/ADR-253-introduce-depracated-state.md b/content/ADR-253-introduce-depracated-state.md index 7dab20d7..aa283d94 100644 --- a/content/ADR-253-introduce-depracated-state.md +++ b/content/ADR-253-introduce-depracated-state.md @@ -12,7 +12,7 @@ authors: ## Abstract -This ADR proposes introducing a new **Deprecated** status for ADRs that are no longer relevant due to changes in Decentraland’s architecture, clients, or feature set. The goal is to improve clarity by distinguishing between ADRs that were once implemented and valid but are now outdated, versus those that were never accepted or implemented. +This ADR proposes introducing a new **Deprecated** status for ADRs that are no longer relevant due to changes in Decentraland’s architecture, protocol, clients, or feature set. The goal is to improve clarity by distinguishing between ADRs that were once implemented and valid but are now outdated, versus those that were never accepted or implemented. ## Context, Reach & Prioritization @@ -22,7 +22,7 @@ The **Withdrawn** status implies that an ADR was abandoned or deemed incorrect b Introducing a **Deprecated** status will: -- Clearly identify ADRs that have been rendered obsolete due to changes in architecture or feature sets. +- Clearly identify ADRs that have been rendered obsolete due to changes in protocol or feature sets. - Preserve the historical context of past decisions while indicating that they are no longer applicable. - Reduce confusion among developers and stakeholders regarding the current relevance of ADRs. @@ -74,7 +74,7 @@ The full list of ADR states will now include: - **Stagnant**: ADRs that are inactive for over 6 months in Draft, Review, or Last Call. - **Withdrawn**: The ADR was abandoned or rejected and will not be pursued further. - **Living**: The ADR is designed to be continually updated and does not reach finality (e.g., ADR-1). -- **Deprecated**: The ADR was once Final and implemented but is now outdated or no longer relevant due to architectural changes. +- **Deprecated**: The ADR was once Final and implemented but is now outdated or no longer relevant due to protocol changes. ### Deprecated State Requirements From 56e9b41c29c94c8be678a4879881398debd6cfa4 Mon Sep 17 00:00:00 2001 From: Aga Date: Tue, 26 Nov 2024 16:35:24 +0000 Subject: [PATCH 4/4] Updated status Signed-off-by: Aga --- ...racated-state.md => ADR-277-introduce-depracated-state.md} | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename content/{ADR-253-introduce-depracated-state.md => ADR-277-introduce-depracated-state.md} (98%) diff --git a/content/ADR-253-introduce-depracated-state.md b/content/ADR-277-introduce-depracated-state.md similarity index 98% rename from content/ADR-253-introduce-depracated-state.md rename to content/ADR-277-introduce-depracated-state.md index aa283d94..660f7a2b 100644 --- a/content/ADR-253-introduce-depracated-state.md +++ b/content/ADR-277-introduce-depracated-state.md @@ -1,9 +1,9 @@ --- layout: adr -adr: 253 # replace this number with the PR or ISSUE number +adr: 277 # replace this number with the PR or ISSUE number title: Introducing the "Deprecated" State for ADRs date: 2024-11-15 -status: Draft +status: Review type: Meta spdx-license: CC0-1.0 authors: