From 523a8dc035e81b9d9a9185fae6220d9e3fdac476 Mon Sep 17 00:00:00 2001 From: Jeeyong Um Date: Fri, 19 Jul 2024 22:52:29 +0900 Subject: [PATCH] Add RFC section for open discussion --- .vitepress/config.mts | 18 ++-- PROCESS.md => architecture/PROCESS.md | 4 +- README.md => architecture/README.md | 0 .../adr-template.md | 0 index.md | 10 +-- rfc/PROCESS.md | 62 ++++++++++++++ rfc/README.md | 38 +++++++++ rfc/rfc-template.md | 83 +++++++++++++++++++ 8 files changed, 203 insertions(+), 12 deletions(-) rename PROCESS.md => architecture/PROCESS.md (93%) rename README.md => architecture/README.md (100%) rename adr-template.md => architecture/adr-template.md (100%) create mode 100644 rfc/PROCESS.md create mode 100644 rfc/README.md create mode 100644 rfc/rfc-template.md diff --git a/.vitepress/config.mts b/.vitepress/config.mts index 64235b5..d817055 100644 --- a/.vitepress/config.mts +++ b/.vitepress/config.mts @@ -3,23 +3,31 @@ import { defineConfig } from 'vitepress' // https://vitepress.dev/reference/site-config export default defineConfig({ title: "Noir", - description: "Noir Architecture Decision Records", + description: "Noir Documentation", base: "/adr/", themeConfig: { // https://vitepress.dev/reference/default-theme-config nav: [ { text: 'Home', link: '/' }, - { text: 'ADRs', link: '/README' } + { text: 'ADR', link: '/architecture/README' }, + { text: 'RFC', link: '/rfc/README' } ], sidebar: [ { - text: 'ADRs', + text: 'ADR', items: [ - { text: 'Architecture Decision Records', link: '/README' }, - { text: 'ADR Creation Process', link: '/PROCESS' } + { text: 'Architecture Decision Records (ADR)', link: '/architecture/README' }, + { text: 'ADR Creation Process', link: '/architecture/PROCESS' } ] }, + { + text: 'RFC', + items: [ + { text: 'Request for Comments', link: '/rfc/README' }, + { text: 'RFC Creation Process', link: '/rfc/PROCESS' } + ] + } ], socialLinks: [ diff --git a/PROCESS.md b/architecture/PROCESS.md similarity index 93% rename from PROCESS.md rename to architecture/PROCESS.md index bca4cdf..925f31b 100644 --- a/PROCESS.md +++ b/architecture/PROCESS.md @@ -2,7 +2,7 @@ 1. Copy the `adr-template.md` file. Use the following filename pattern: `adr-next_number-title.md` 2. Create a draft Pull Request if you want to get an early feedback. -3. Make sure the context and solution is clear and well documented. +3. Make sure the context and a solution are clear and well documented. 4. Add an entry to a list in the [README](./README.md) file. 5. Create a Pull Request to propose a new ADR. @@ -46,7 +46,7 @@ DRAFT -> PROPOSED -> LAST CALL yyyy-mm-dd -> ACCEPTED | REJECTED -> SUPERSEDED b * `DRAFT`: [optional] an ADR which is work in progress, not being ready for a general review. This is to present an early work and get an early feedback in a Draft Pull Request form. * `PROPOSED`: an ADR covering a full solution architecture and still in the review - project stakeholders haven't reached an agreed yet. -* `LAST CALL `: [optional] clear notify that we are close to accept updates. Changing a status to `LAST CALL` means that social consensus (of Cosmos SDK maintainers) has been reached and we still want to give it a time to let the community react or analyze. +* `LAST CALL `: [optional] clear notify that we are close to accept updates. Changing a status to `LAST CALL` means that social consensus (of Noir maintainers) has been reached and we still want to give it a time to let the community react or analyze. * `ACCEPTED`: ADR which will represent a currently implemented or to be implemented architecture design. * `REJECTED`: ADR can go from PROPOSED or ACCEPTED to rejected if the consensus among project stakeholders will decide so. * `SUPERSEDED by ADR-xxx`: ADR which has been superseded by a new ADR. diff --git a/README.md b/architecture/README.md similarity index 100% rename from README.md rename to architecture/README.md diff --git a/adr-template.md b/architecture/adr-template.md similarity index 100% rename from adr-template.md rename to architecture/adr-template.md diff --git a/index.md b/index.md index 40c4731..e2ccc87 100644 --- a/index.md +++ b/index.md @@ -4,14 +4,14 @@ layout: home hero: name: "Noir" - tagline: Architecture Decision Records + text: Documentation actions: - theme: brand - text: ADRs - link: /README + text: ADR + link: /architecture/README - theme: alt - text: Process - link: /PROCESS + text: RFC + link: /rfc/README features: - title: Feature A diff --git a/rfc/PROCESS.md b/rfc/PROCESS.md new file mode 100644 index 0000000..204edbb --- /dev/null +++ b/rfc/PROCESS.md @@ -0,0 +1,62 @@ +# RFC Creation Process + +1. Copy the `rfc-template.md` file. Use the following filename pattern: `rfc-next_number-title.md` +2. Create a draft Pull Request if you want to get early feedback. +3. Make sure the context and solution are clear and well-documented. +4. Add an entry to the list in the [README](./README.md) file. +5. Create a Pull Request to propose a new RFC. + +## What is a RFC? + +A RFC is a sort of async whiteboarding session. It is meant to replace the need for a distributed team to come together to make a decision. Currently, the Noir team and contributors are distributed around the world. The team conducts working groups to have a synchronous discussion and a RFC can be used to capture the discussion for a wider audience to better understand the changes that are coming to the software. + +The main difference the Noir is defining as a differentiation between RFCs and ADRs is that one is to come to consensus and circulate information about a potential change or feature. An ADR is used if there is already consensus on a feature or change and there is not a need to articulate the change coming to the software. An ADR will articulate the changes and have a lower amount of communication. + +## RFC life cycle + +RFC creation is an **iterative** process. A RFC is meant as a distributed collaboration session, it may have many comments and is usually the by-product of no working group or synchronous communication. + +1. Proposals could start with a new GitHub Issue, be a result of existing Issues or a discussion. + +2. A RFC doesn't have to arrive to `main` with an _accepted_ status in a single PR. If the motivation is clear and the solution is sound, we SHOULD be able to merge it and keep a _proposed_ status. It's preferable to have an iterative approach rather than long, not merged Pull Requests. + +3. If a _proposed_ RFC is merged, then it should clearly document outstanding issues either in the RFC document notes or in a GitHub Issue. + +4. The PR SHOULD always be merged. In the case of a faulty RFC, we still prefer to merge it with a _rejected_ status. The only time the RFC SHOULD NOT be merged is if the author abandons it. + +5. Merged RFCs SHOULD NOT be pruned. + +6. If there is consensus and enough feedback then the RFC can be accepted. + +> Note: A RFC is written when there is no working group or team session on the problem. RFCs are meant as a distributed whiteboarding session. If there is a working group on the proposal there is no need to have a RFC as there is synchronous whiteboarding going on. + +### RFC status + +Status has two components: + +```text +{CONSENSUS STATUS} +``` + +#### Consensus Status + +```text +DRAFT -> PROPOSED -> LAST CALL yyyy-mm-dd -> ACCEPTED | REJECTED -> SUPERSEDED by RFC-xxx + \ | + \ | + v v + ABANDONED +``` + +* `DRAFT`: [optional] a RFC which is work in progress, not being ready for a general review. This is to present early work and get early feedback in a Draft Pull Request form. +* `PROPOSED`: a RFC covering a full solution architecture and still in review - project stakeholders haven't reached an agreement yet. +* `LAST CALL `: [optional] clearly notify that we are close to accepting updates. Changing a status to `LAST CALL` means that social consensus (of Noir maintainers) has been reached and we still want to give it time to let the community react or analyze. +* `ACCEPTED`: RFC which will represent a currently implemented or to be implemented architecture design. +* `REJECTED`: RFC can go from PROPOSED or ACCEPTED to rejected if the consensus among project stakeholders decides so. +* `SUPERSEDED by RFC-xxx`: RFC which has been superseded by a new RFC. +* `ABANDONED`: the RFC is no longer pursued by the original authors. + +## Language used in RFC + +* The background/goal should be written in the present tense. +* Avoid using a first-person form. diff --git a/rfc/README.md b/rfc/README.md new file mode 100644 index 0000000..94ece11 --- /dev/null +++ b/rfc/README.md @@ -0,0 +1,38 @@ +--- +sidebar_position: 1 +--- + +# Requests for Comments + +A Request for Comments (RFC) is a record of discussion on an open-ended topic +related to the design and implementation of the Noir, for which no +immediate decision is required. + +The purpose of an RFC is to serve as a historical record of a high-level +discussion that might otherwise only be recorded in an ad-hoc way (for example, +via gists or Google docs) that are difficult to discover for someone after the +fact. An RFC _may_ give rise to more specific architectural _decisions_ for +the Noir, but those decisions must be recorded separately in +[Architecture Decision Records (ADR)](../architecture/README). + +As a rule of thumb, if you can articulate a specific question that needs to be +answered, write an ADR. If you need to explore the topic and get input from +others to know what questions need to be answered, an RFC may be appropriate. + +## RFC Content + +An RFC should provide: + +* A **changelog**, documenting when and how the RFC has changed. +* An **abstract**, briefly summarizing the topic so the reader can quickly tell + whether it is relevant to their interest. +* Any **background** a reader will need to understand and participate in the + substance of the discussion (links to other documents are fine here). +* The **discussion**, the primary content of the document. + +The [rfc-template.md](./rfc-template.md) file includes placeholders for these +sections. + +## Table of Contents + + diff --git a/rfc/rfc-template.md b/rfc/rfc-template.md new file mode 100644 index 0000000..f4e79fb --- /dev/null +++ b/rfc/rfc-template.md @@ -0,0 +1,83 @@ +# RFC {RFC-NUMBER}: {TITLE} + +## Changelog + +* {date}: {changelog} + +## Background + +> The next section is the "Background" section. This section should be at least two paragraphs and can take up to a whole +> page in some cases. The guiding goal of the background section is: as a newcomer to this project (new employee, team +> transfer), can I read the background section and follow any links to get the full context of why this change is +> necessary? +> +> If you can't show a random engineer the background section and have them acquire nearly full context on the necessity +> for the RFC, then the background section is not full enough. To help achieve this, link to prior RFCs, discussions, and +> more here as necessary to provide context so you don't have to simply repeat yourself. + + +## Proposal + +> The next required section is "Proposal" or "Goal". Given the background above, this section proposes a solution. +> This should be an overview of the "how" for the solution, but for details further sections will be used. + + +## Abandoned Ideas (Optional) + +> As RFCs evolve, it is common that there are ideas that are abandoned. Rather than simply deleting them from the +> document, you should try to organize them into sections that make it clear they're abandoned while explaining why they +> were abandoned. +> +> When sharing your RFC with others or having someone look back on your RFC in the future, it is common to walk the same +> path and fall into the same pitfalls that we've since matured from. Abandoned ideas are a way to recognize that path +> and explain the pitfalls and why they were abandoned. + +## Decision + +> This section describes alternative designs to the chosen design. This section +> is important and if an adr does not have any alternatives then it should be +> considered that the ADR was not thought through. + +## Consequences (optional) + +> This section describes the resulting context, after applying the decision. All +> consequences should be listed here, not just the "positive" ones. A particular +> decision may have positive, negative, and neutral consequences, but all of them +> affect the team and project in the future. + +### Backwards Compatibility + +> All ADRs that introduce backwards incompatibilities must include a section +> describing these incompatibilities and their severity. The ADR must explain +> how the author proposes to deal with these incompatibilities. ADR submissions +> without a sufficient backwards compatibility treatise may be rejected outright. + +### Positive + +> {positive consequences} + +### Negative + +> {negative consequences} + +### Neutral + +> {neutral consequences} + + + +### References + +> Links to external materials needed to follow the discussion may be added here. +> +> In addition, if the discussion in a request for comments leads to any design +> decisions, it may be helpful to add links to the ADR documents here after the +> discussion has settled. + +## Discussion + +> This section contains the core of the discussion. +> +> There is no fixed format for this section, but ideally changes to this +> section should be updated before merging to reflect any discussion that took +> place on the PR that made those changes.