From f97e998b9f8f0af97167319f6862cd83ba35af1d Mon Sep 17 00:00:00 2001 From: Agnieszka Besz Date: Thu, 28 Nov 2024 17:48:23 +0000 Subject: [PATCH 1/4] docs: updating ADR 277, making changes to introduce deprecated state --- .site-generator/index.js | 25 ++++++-- .site-generator/scss/main.scss | 6 ++ README.md | 4 +- content/ADR-1-adr-process.md | 62 ++++++++++--------- content/ADR-277-introduce-depracated-state.md | 2 +- 5 files changed, 62 insertions(+), 37 deletions(-) diff --git a/.site-generator/index.js b/.site-generator/index.js index c1d7e96c..00a57127 100644 --- a/.site-generator/index.js +++ b/.site-generator/index.js @@ -16,24 +16,25 @@ module.exports = function ({ context }) { page.layout = "adr" page.matterfront.layout = "adr" if (page.matterfront["spdx-license"] !== "CC0-1.0") - throw new Error(`Page ADR-${page.matterfront.adr} as invalid license: ${page.matterfront["spdx-license"]}`) + throw new Error(`Page ADR-${page.matterfront.adr} has an invalid license: ${page.matterfront["spdx-license"]}`) checkAdrStatus(page) } else if (page.matterfront.rfc) { console.error(page) - throw new Error(`RFC are deprecated, plase upgrade. More info in ADR-1`) + throw new Error(`RFC are deprecated, please upgrade. More info in ADR-1`) } } } function checkAdrStatus(page) { - const validStatuses = new Set(["Draft", "Review", "LastCall", "Final", "Stagnant", "Withdrawn", "Living"]) + const validStatuses = new Set(["Draft", "Review", "LastCall", "Final", "Stagnant", "Withdrawn", "Living", "Deprecated"]) const validTypes = new Set(["RFC", "Standards Track", "Meta"]) + if (!page.matterfront.status) throw new Error("ADR-" + page.matterfront.adr + " has no `status`") if (!page.matterfront.type) throw new Error("ADR-" + page.matterfront.adr + " has no `type`") if (!validTypes.has(page.matterfront.type)) throw new Error( - "ADR-" + + "ADR-" + page.matterfront.adr + " has invalid `type: " + page.matterfront.type + @@ -43,11 +44,25 @@ function checkAdrStatus(page) { if (!validStatuses.has(page.matterfront.status)) throw new Error( - "ADR-" + + "ADR-" + page.matterfront.adr + " has invalid `status: " + page.matterfront.status + "`, valid statuses are: " + Array.from(validStatuses).join(",") ) + + if (page.matterfront.status === "Deprecated" && !page.matterfront["deprecated-reason"]) + throw new Error( + "ADR-" + + page.matterfront.adr + + " is marked as `Deprecated` but has no `deprecated-reason`" + ) + + if (page.matterfront.status === "Withdrawn" && !page.matterfront["withdrawal-reason"]) + throw new Error( + "ADR-" + + page.matterfront.adr + + " is marked as `Withdrawn` but has no `withdrawal-reason`" + ) } diff --git a/.site-generator/scss/main.scss b/.site-generator/scss/main.scss index 23bb5297..408df153 100755 --- a/.site-generator/scss/main.scss +++ b/.site-generator/scss/main.scss @@ -53,6 +53,12 @@ color: magenta; } + .status-Deprecated { + color: #555; + text-decoration: line-through !important; + font-style: italic; + } + .status-Withdrawn { text-decoration: line-through !important; color: #999; diff --git a/README.md b/README.md index 495aab8b..fd8bec1a 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,7 @@ states: - LastCall - Stagnant - Withdrawn +- Deprecated spdx-license: CC0-1.0 --- @@ -19,7 +20,7 @@ ADR stands for _Architecture Decision Record_. An ADR is a design document provi ## How do ADRs work? -Read [the ADR explaining the rationale](/content/ADR-1-adr-process.md) for a detailed explaination. +Read [the ADR explaining the rationale](/content/ADR-1-adr-process.md) for a detailed explanation. ### ADR Process @@ -54,3 +55,4 @@ There are three types of ADRs: - A **Meta** ADR describes a process surrounding Decentraland or proposes a change to (or an event in) a process. Process ADRs are like Standards Track ADRs but apply to areas other than the Decentraland protocol itself. - An **RFC** describes a Decentraland design issue, or provides general guidelines or information to the Decentraland community. RFCs do not necessarily represent Decentraland community consensus or a recommendation, so users and implementers are free to ignore RFCs or follow their advice. + Final --> Deprecated diff --git a/content/ADR-1-adr-process.md b/content/ADR-1-adr-process.md index 193c4924..d883343b 100644 --- a/content/ADR-1-adr-process.md +++ b/content/ADR-1-adr-process.md @@ -23,7 +23,7 @@ For Decentraland implementers, ADRs are a convenient way to track the progress o There are three types of ADR: -- A **Standards Track** ADR describes any change that affects most or all Decentraland implementations, such as—a change to the synchronzation protocol, a change in deployments validity rules, proposed application standards/conventions, or any change or addition that affects the interoperability of applications using Decentraland. Standards Track ADRs consist of three parts—a design document, an implementation, and (if warranted) an update to the [formal specification](https://github.com/decentraland/yellowpaper). +- A **Standards Track** ADR describes any change that affects most or all Decentraland implementations, such as—a change to the synchronization protocol, a change in deployments validity rules, proposed application standards/conventions, or any change or addition that affects the interoperability of applications using Decentraland. Standards Track ADRs consist of three parts—a design document, an implementation, and (if warranted) an update to the [formal specification](https://github.com/decentraland/yellowpaper). - A **Meta** ADR describes a process surrounding Decentraland or proposes a change to (or an event in) a process. Process ADRs are like Standards Track ADRs but apply to areas other than the Decentraland protocol itself. @@ -62,6 +62,8 @@ flowchart TB Review <--> Stagnant Draft <--> Stagnant + Final --> Deprecated + ``` **Idea** - An idea that is pre-draft. This is not tracked within the ADR Repository as a text file, it is recommended to start with an issue or discussion. @@ -76,21 +78,23 @@ If this period results in necessary normative changes it will revert the ADR to **Final** - This ADR represents the final standard. A Final ADR exists in a state of finality and should only be updated to correct errata and add non-normative clarifications. -**Stagnant** - Any ADR in `Draft` or `Review` or `Last Call` if inactive for a period of 6 months or greater is moved to `Stagnant`. An ADR may be resurrected from this state by Authors or ADR Editors through moving it back to `Draft` or it's earlier status. If not resurrected, a proposal may stay forever in this status. +**Stagnant** - Any ADR in `Draft` or `Review` or `Last Call` if inactive for a period of 6 months or greater is moved to `Stagnant`. An ADR may be resurrected from this state by Authors or ADR Editors through moving it back to `Draft` or its earlier status. If not resurrected, a proposal may stay forever in this status. -**Withdrawn** - The ADR Author(s) have withdrawn the proposed ADR. This state has finality and can no longer be resurrected using this ADR number. If the idea is pursued at later date it is considered a new proposal. +**Withdrawn** - The ADR Author(s) have withdrawn the proposed ADR. This state has finality and can no longer be resurrected using this ADR number. If the idea is pursued at a later date it is considered a new proposal. **Living** - A special status for ADRs that are designed to be continually updated and not reach a state of finality. This includes most notably ADR-1. +**Deprecated** - An ADR that was previously marked as `Final` and implemented but has become obsolete or no longer relevant due to protocol or feature changes. Deprecated ADRs must include a Deprecation Reason explaining their obsolescence and, where applicable, link to newer ADRs that supersede them. + ## What belongs in a successful ADR? Each ADR should have the following parts: -- Preamble - RFC 822 style headers containing metadata about the ADR, including the ADR number, a short descriptive title (limited to a maximum of 44 characters), a description (limited to a maximum of 140 characters), and the author details. Irrespective of the category, the title and description should not include ADR number. -- Abstract - Abstract is a multi-sentence (short paragraph) technical summary. This should be a very terse and human-readable version of the document section. **Someone should be able to read only the abstract to get the gist of what this document is about in its current state.** Abstracts should be always up to date with the current state of the document. -- Context, Reach & Prioritization - Go into detail about the subject in question. Why is this decision important? The urgency of the decision? Datapoints and related background information. Vocabulary and key terms. -- Solution Space Exploration - Discuss the potential alternatives and their impact. What alternatives are being considered, their benefits, their costs (team resources, money, time frames), and mitigations for any drawbacks. -- Specification - The technical specification should describe the syntax and semantics of any new feature. +- **Preamble** - RFC 822 style headers containing metadata about the ADR, including the ADR number, a short descriptive title (limited to a maximum of 44 characters), a description (limited to a maximum of 140 characters), and the author details. Irrespective of the category, the title and description should not include ADR number. +- **Abstract** - Abstract is a multi-sentence (short paragraph) technical summary. This should be a very terse and human-readable version of the document section. **Someone should be able to read only the abstract to get the gist of what this document is about in its current state.** Abstracts should be always up to date with the current state of the document. +- **Context, Reach & Prioritization** - Go into detail about the subject in question. Why is this decision important? The urgency of the decision? Datapoints and related background information. Vocabulary and key terms. +- **Solution Space Exploration** - Discuss the potential alternatives and their impact. What alternatives are being considered, their benefits, their costs (team resources, money, time frames), and mitigations for any drawbacks. +- **Specification** - The technical specification should describe the syntax and semantics of any new feature. ## Picking an ADR number @@ -104,25 +108,17 @@ ADRs should be written in [markdown](https://github.com/adam-p/markdown-here/wik Each ADR must begin with an [RFC 822](https://www.ietf.org/rfc/rfc822.txt) style header preamble, preceded and followed by three hyphens (`---`). This header is also termed ["front matter" by Jekyll](https://jekyllrb.com/docs/front-matter/). The headers must appear in the following order. -`adr`: _ADR number_ (this is determined by the ADR editor) - -`title`: _The ADR title is a few words, not a complete sentence_ - -`description`: _Description is one full (short) sentence_ - -`authors`: _The list of the author's GitHub username(s)._ - -`discussion`: _The url pointing to the official discussion thread_ - -`status`: _Draft, Review, Last Call, Final, Stagnant, Withdrawn, Living_ - -`last-call-deadline`: _The date last call period ends on_ (Optional field, only needed when status is `Last Call`) - -`type`: _One of `Standards Track`, `Meta`, or `ADR`_ - -`date`: _Date the ADR was created on_ - -`withdrawal-reason`: _A sentence explaining why the ADR was withdrawn._ (Optional field, only needed when status is `Withdrawn`) +- `adr`: _ADR number_ (this is determined by the ADR editor) +- `title`: _The ADR title is a few words, not a complete sentence_ +- `description`: _Description is one full (short) sentence_ +- `authors`: _The list of the author's GitHub username(s)._ +- `discussion`: _The url pointing to the official discussion thread_ +- `status`: _Draft, Review, Last Call, Final, Stagnant, Withdrawn, Living, Deprecated_ +- `last-call-deadline`: _The date last call period ends on_ (Optional field, only needed when status is `Last Call`) +- `type`: _One of `Standards Track`, `Meta`, or `ADR`_ +- `date`: _Date the ADR was created on_ +- `withdrawal-reason`: _A sentence explaining why the ADR was withdrawn._ (Optional field, only needed when status is `Withdrawn`) +- `deprecated-reason`: _A sentence explaining why the ADR was deprecated._ (Optional field, only needed when status is `Deprecated`) Headers that permit lists must separate elements with commas. @@ -156,8 +152,6 @@ Links to external resources **SHOULD NOT** be included. External resources may d References to other ADRs should follow the format `ADR-N` where `N` is the ADR number you are referring to. Each ADR that is referenced in an ADR **MUST** be accompanied by an absolute markdown link to the absolute rendered path i.e. `/adr/ADR-1`. - - ## Auxiliary Files Images, diagrams and auxiliary files should be included in a subdirectory of the `public/resources` folder for that ADR as follows: `public/resources/ADR-N` (where **N** is to be replaced with the ADR number). When linking to an image in the ADR public/resources, use absolute links such as `/resources/ADR-1/image.png`. @@ -209,7 +203,15 @@ ADRs are encouraged to follow [RFC 2119](https://www.ietf.org/rfc/rfc2119.html) This document was derived heavily from [Ethereum EIPs](https://github.com/ethereum/eips) which was also derived from [Bitcoin's BIP-0001](https://github.com/bitcoin/bips) written by Amir Taaki which in turn was derived from [Python's PEP-0001](https://peps.python.org/). In many places text was simply copied and modified. Although the PEP-0001 text was written by Barry Warsaw, Jeremy Hylton, and David Goodger. -The initial document for ADRs for Decentraland can be found in the git history of this file and it was derived from [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) by Michael Nygard +The initial document for ADRs for Decentraland can be found in the git history of this file and it was derived from [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) by Michael Nygard. 1. [Importance of architecture decisions](http://www.computer.org/portal/web/csdl/doi/10.1109/MS.2009.52) 2. [Documenting software architectures](http://www.sei.cmu.edu/library/abstracts/books/0321552687.cfm) + +## Changelog + +### [2024-11-28] +- **Added `Deprecated` Status**: + - Introduced the `Deprecated` status to identify ADRs that were previously marked as `Final` but are now obsolete due to changes in Decentraland's architecture, protocol, or feature set. + - Deprecated ADRs must include a `deprecated-reason` explaining their obsolescence and, if applicable, link to newer ADRs that supersede them. + - More details https://adr.decentraland.org/adr/ADR-277 \ No newline at end of file diff --git a/content/ADR-277-introduce-depracated-state.md b/content/ADR-277-introduce-depracated-state.md index 660f7a2b..57c672a5 100644 --- a/content/ADR-277-introduce-depracated-state.md +++ b/content/ADR-277-introduce-depracated-state.md @@ -3,7 +3,7 @@ layout: adr adr: 277 # replace this number with the PR or ISSUE number title: Introducing the "Deprecated" State for ADRs date: 2024-11-15 -status: Review +status: Living type: Meta spdx-license: CC0-1.0 authors: From 50bd60290139e9545506f78fdf4c5eaa89f676c9 Mon Sep 17 00:00:00 2001 From: Agnieszka Besz Date: Thu, 28 Nov 2024 17:49:40 +0000 Subject: [PATCH 2/4] Removed check for Withdrawn reason --- .site-generator/index.js | 7 ------- 1 file changed, 7 deletions(-) diff --git a/.site-generator/index.js b/.site-generator/index.js index 00a57127..895fb778 100644 --- a/.site-generator/index.js +++ b/.site-generator/index.js @@ -58,11 +58,4 @@ function checkAdrStatus(page) { page.matterfront.adr + " is marked as `Deprecated` but has no `deprecated-reason`" ) - - if (page.matterfront.status === "Withdrawn" && !page.matterfront["withdrawal-reason"]) - throw new Error( - "ADR-" + - page.matterfront.adr + - " is marked as `Withdrawn` but has no `withdrawal-reason`" - ) } From 79ec949d172d92b67cb5abe3b044db2a0a525749 Mon Sep 17 00:00:00 2001 From: Agnieszka Besz Date: Thu, 28 Nov 2024 18:06:58 +0000 Subject: [PATCH 3/4] Fixing graph --- README.md | 7 +++++-- content/ADR-1-adr-process.md | 1 + content/ADR-277-introduce-depracated-state.md | 3 ++- 3 files changed, 8 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index fd8bec1a..613cb73a 100644 --- a/README.md +++ b/README.md @@ -39,11 +39,14 @@ flowchart TB Review --> Withdrawn LastCall --> Withdrawn - + LastCall <--> Stagnant Review <--> Stagnant Draft <--> Stagnant - + + + Final --> Deprecated + Living --> Deprecated ``` ## ADR Types diff --git a/content/ADR-1-adr-process.md b/content/ADR-1-adr-process.md index d883343b..de516a82 100644 --- a/content/ADR-1-adr-process.md +++ b/content/ADR-1-adr-process.md @@ -63,6 +63,7 @@ flowchart TB Draft <--> Stagnant Final --> Deprecated + Living --> Deprecated ``` diff --git a/content/ADR-277-introduce-depracated-state.md b/content/ADR-277-introduce-depracated-state.md index 57c672a5..c485c6d3 100644 --- a/content/ADR-277-introduce-depracated-state.md +++ b/content/ADR-277-introduce-depracated-state.md @@ -1,7 +1,7 @@ --- layout: adr adr: 277 # replace this number with the PR or ISSUE number -title: Introducing the "Deprecated" State for ADRs +title: Introducing the Deprecated State for ADRs date: 2024-11-15 status: Living type: Meta @@ -62,6 +62,7 @@ flowchart TB Draft <--> Stagnant Final --> Deprecated + Living --> Deprecated ``` The full list of ADR states will now include: From 10a34a40b157d2e0474b9325a06d3f3a31856ae7 Mon Sep 17 00:00:00 2001 From: Agnieszka Besz Date: Thu, 28 Nov 2024 18:09:48 +0000 Subject: [PATCH 4/4] Updated status --- content/ADR-277-introduce-depracated-state.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/ADR-277-introduce-depracated-state.md b/content/ADR-277-introduce-depracated-state.md index c485c6d3..3043b906 100644 --- a/content/ADR-277-introduce-depracated-state.md +++ b/content/ADR-277-introduce-depracated-state.md @@ -3,7 +3,7 @@ layout: adr adr: 277 # replace this number with the PR or ISSUE number title: Introducing the Deprecated State for ADRs date: 2024-11-15 -status: Living +status: Final type: Meta spdx-license: CC0-1.0 authors: