From 5ad83e677bec79158c2a2cdc7cb011b1d8e99032 Mon Sep 17 00:00:00 2001 From: nlf Date: Wed, 8 Mar 2023 10:40:45 -0800 Subject: [PATCH] feat: rewrite README to describe new rfc process --- README.md | 174 ++++++++++++++++-------------------------------------- 1 file changed, 51 insertions(+), 123 deletions(-) diff --git a/README.md b/README.md index 7bb1f141..a7b6d071 100644 --- a/README.md +++ b/README.md @@ -1,180 +1,108 @@ # RFC Process -This document describes the RFC process for the [npm -CLI](https://github.com/npm/cli), and provides a way for the [npm CLI -team](https://github.com/orgs/npm/teams/cli-team) and the wider community -to have discussions about the features and direction of the package -manager. +This document describes the RFC process for the [npm CLI](https://github.com/npm/cli), and provides a way for the [npm CLI team](https://github.com/orgs/npm/teams/cli-team) and the wider community to have discussions about the features and direction of the package manager. ## What is an RFC? -The name is a reference to the **IETF's Request For Comments** process, and -involves a document or series of documents which are drafted, reviewed, and -eventually ratified (approved) by the npm team through discussion -among those interested, both within and outside of the npm team. +The name is a reference to the **IETF's Request For Comments** process. In the case of the npm CLI these are implemented in the form of a GitHub issue in this repository. The issue will be drafted, reviewed, discussed and eventually ratified by the npm team with the help of our community members during our RFC review calls. -An RFC can propose any change to the npm CLI itself, and may include npm -registry changes meant to support that CLI change. +An RFC can propose any change to the npm CLI itself, and may include npm registry changes meant to support that CLI change. It is also important to be aware that an RFC being ratified does not guarantee that it will be implemented. The npm CLI team welcomes outside contributors, and these approved RFCs are a good way to find tasks to work on. ## Rough Consensus -The development of new features within the npm CLI follows a [Rough -Consensus](https://tools.ietf.org/html/rfc7282) model, similar to the IETF. +The development of new features within the npm CLI follows a [Rough Consensus](https://tools.ietf.org/html/rfc7282) model, similar to the IETF. -The following points are intended to help you understand and participate in -this process productively. +This consensus is gathered from the npm CLI team, as well as all community attendees of RFC review calls as well as community members who choose to comment on an RFC issue. If a community member has an objection, it is appreciated if they are also able to attend an RFC review call in order to have a real time conversation about their concerns. + +The following points are intended to help you understand and participate in this process productively. ### Scope of This Process -This RFC process is limited to issues concerning the [npm -cli](https://github.com/npm/cli) and the web services that support it. +This RFC process is limited to issues concerning the [npm CLI](https://github.com/npm/cli). -Of course we operate within a broad community ecosystem, and will often -choose to implement features in a way that is compatible with other package -management tools in the JavaScript community. However, if a given proposal -cannot or will not be implemented by other package managers, that is not in -itself reason enough to abandon a proposal. We are here to make _npm_ -better. +Of course we operate within a broad community ecosystem, and will often choose to implement features in a way that is compatible with other package management tools in the JavaScript community. However, if a given proposal cannot or will not be implemented by other package managers, that is not in itself reason enough to abandon a proposal. We are here to make _npm_ better. -### Full Consensus is Not The Goal +### Iterate on Building Blocks -It is not our intention, or within our ability, to accomodate every -possible objection to any given proposal. It _is_ our intention to surface -all such objections, and make an informed decision as to whether the -objection can be addressed, should be accepted, or is reason enough to -abandon the proposal entirely. +Frequently an RFC will be proposed or even fully specified in an ADR, and upon analysis, the feedback might be to cut it into separate RFCs, or implement another proposal first. -We encourage you to participate in these discussions, and to feel free and -comfortable bringing up any objections that you have or can imagine (even -if you don't entirely agree with the objection!) +This can be frustrating at times, but it ensures that we are taking care to improve npm iteratively, with thorough consideration of each step along the way. -Our job together then, is to ensure that the objection is given a fair -hearing, and is fully understood. Then (either in the pull request -comments, or in our OpenRFC meetings), we will decide whether the proposal -should be modified in light of the objection, or the objection should be -ignored, or if the proposal should be abandoned. +## How do I create an RFC? -If an objection is brought up a second time without any relevant changes, -after having already been addressed, then it will be ignored. Only _new_ -objections merit new or continued consideration. +* Visit https://github.com/npm/rfcs +* Open a new issue using the RFC template -### Iterate on Building Blocks +## How does review work? -Frequently a feature will be proposed or even fully specified in an RFC, -and upon analysis, the feedback might be to cut it into separate RFCs, or -implement another proposal first. +The official place for discussion for a proposed RFC is its issue. Anyone, both npm collaborators and non-collaborators, may participate in the discussion and ask questions and provide (constructive) feedback. Keep in mind that only npm collaborators are able to ratify the RFC itself, even if other users can comment. -This can be frustrating at times, but it ensures that we are taking care -to improve npm iteratively, with thorough consideration of each step along -the way. +Initial RFC proposals should be reviewed by the npm team and assigned to the agenda of an upcoming RFC discussion within 2 weeks of being opened. It is encouraged for the author of an RFC to attend this call, but if they are not able to for any reason discussions during the call will be summarized in the issue and responses can be gathered asynchronously. -### Implementation as Exploration +All discussions surrounding an RFC are covered by the [npm Code of Conduct](https://www.npmjs.com/policies/conduct). Please keep conversations constructive, civil, and low-temperature. If tensions flare during discussion, the npm team may, at its own discretion, moderate, remove, or edit posts, as well as locking the discussion on that PR or the entire RFCs repository. -Typically, RFCs are discussed and ratified prior to implementation. -However, this is not always the case! Occasionally, we will develop a -feature then write an RFC after the fact to describe and discuss it prior -to merging into the latest npm release. +## How do RFCs get ratified? -Very often, an RFC will be difficult to examine without running code. In -those cases, we may opt to develop a proof of concept (or even fully -production-ready implementation) of an RFC in process, in order to test it -in reality before accepting it. +When the scheduled RFC call takes place, the npm team and the community will read and discuss the changes detailed in the RFC. It is possible that the discussion will be carried over to a future RFC call due to time constraints or needing further discussion. Once there is rough consensus amongst the participants of the call and all objections have been considered, an RFC is considered ratified and will be labeled as "ready for work". -Even when an RFC _is_ accepted, during implementation it is common to note -additional objections, features, or decisions that need to be made. In -these cases, we may propose an amendment to a previously ratified RFC. +It is common for an RFC to require multiple rounds of editing to address concerns brought up in the discussion. -### Final Authority +The RFC may be rejected altogether at the discretion of npm collaborators. -The ultimate authority as to the ratification of any given RFC proposal is -the npm CLI team, as they have ultimate authority over the direction and -development of the actual thing these RFCs are about. +Reasons for this may include, but are not limited to: -## How do I create an RFC? +- Objections are raised that are deemed to be relevant to the npm CLI, and cannot be reasonably addressed within the RFC. +- The feature conflicts with another intended feature, or otherwise does not align with the future development direction of the npm CLI. +- The feature described is prohibitively difficult to implement. +- The feature described is better addressed by an alternate proposal. -* Fork https://github.com/npm/rfcs -* Copy `accepted/0000-template.md` into `accepted/0000-your-rfc-name.md` -* Fill in and edit the template with your proposal -* Submit a PR to the `npm/rfcs` repo +### Full Consensus is Not The Goal -## How does review work? +It is not our intention, or within our ability, to accommodate every possible objection to any given proposal. It _is_ our intention to surface all such objections, and make an informed decision as to whether the objection can be addressed, should be accepted, or is reason enough to abandon the proposal entirely. -The official place for discussion for a proposed RFC is its pull request. -Anyone, both npm collaborators and non-collaborators, may participate in the -discussion and ask questions and provide (constructive) feedback. Keep in mind -that only npm collaborators are able to ratify the RFC itself, even if other -users can comment. +We encourage you to participate in these discussions, and to feel free and comfortable bringing up any objections that you have or can imagine (even if you don't entirely agree with the objection!) -All discussions surrounding an RFC are covered by the [npm Code of -Conduct](https://www.npmjs.com/policies/conduct). Please keep conversations -constructive, civil, and low-temperature. If tensions flare during discussion, -the npm team may, at its own discretion, moderate, remove, or -edit posts, as well as locking the discussion on that PR or the entire RFCs -repository. +Our job together then, is to ensure that the objection is given a fair hearing, and is fully understood. Then (either in the RFC issue comments, or in our OpenRFC meetings), we will decide whether the proposal should be modified in light of the objection, or the objection should be ignored, or if the proposal should be abandoned. -## How do RFCs get ratified? +If an objection is brought up a second time without any relevant changes, after having already been addressed, then it will be ignored. Only _new_ objections merit new or continued consideration. -An RFC is ratified when there is consensus among npm collaborators that it -should be accepted, and all objections have been considered. At that -point, it will be merged into the `latest` branch, and will be considered -"ratified". +### Final Authority -It is common for an RFC to require multiple rounds of editing to address -concerns brought up in the discussion. +The ultimate authority as to the ratification of any given RFC proposal is the npm CLI team, as they have ultimate authority over the direction and development of the npm CLI. -The RFC may be rejected altogether at the discretion of npm collaborators. -Reasons for this may include, but are not limited to: +Generally, RFCs are discussed and ratified prior to implementation. However, this is not always the case! The npm team may choose, at their discretion, to skip the RFC process and go straight to implementation and ADR. -- Objections are raised that are deemed to be relevant to the npm CLI, and - cannot be reasonably addressed within the RFC. -- The feature conflicts with another intended feature, or otherwise does - not align with the future development direction of the npm CLI. -- The feature described is prohibitively difficult to implement. -- The feature described is better addressed by an alternate proposal. +RFCs submitted by community members, unless approved by the npm team, must go through the RFC process first. A community submitted pull request containing an ADR having had no previous RFC and no communication with the npm team will be closed and the author will be instructed to start at the RFC process instead. ## What happens after ratification? -Once an RFC is ratified, the npm team agrees to merge a corresponding PR -implementing the described changes, provided it passes a standard code -review by the maintainers. It is **not** a guarantee of implementation, nor -does it obligate the npm team itself to implement the requested changes. +Once an RFC is ratified, the issue will be labeled as "ready for work". At this point the npm team and the community have agreed that the feature or change discussed in the RFC is desirable. Any member of the npm team or the community in general is free to comment on the issue declaring their intent to be the DRI (Directly Responsible Individual) for the RFC. -Actual integration into the CLI may also be deferred to a later date, or a -later semver-major CLI release, at the npm collaborators' discretion. All -the RFC does is communicate the team's intention to work in a given -direction. +Ratification is not a guarantee of implementation by the npm team, nor anyone in the community. It is only an indicator that if the feature/change were to be implemented, and that implementation passes code review, the npm team will merge the corresponding work. Merging may be deferred to a later date in the case of breaking changes. Timing of the merge is at the discretion of the npm team. -Actual development work on the npm CLI will be ordered based on priorities -and resources that are well outside the scope of this RFC process. +As a DRI, you are responsible for communication with the npm team, as well as overseeing implementation and creation of an ADR (Architectural Decision Record) representing the changes detailed in the RFC. This is the stage where we start discussing implementation details. The npm team is here to help and will do their best to provide open channels of communication with DRIs in order to answer questions and provide advice. + +Once a DRI has been assigned, they can begin work on the ADR document as well as implementation. An ADR document is intended to describe in detail what decisions have been made about implementation and why. This document will be submitted as a pull request to this repository using the ADR template. The pull request for the ADR will remain open until implementation is complete and ready to be merged. ### Implementation -When the changes described in an RFC have been implemented and merged into the -relevant repository (and thus, due to be released), the corresponding RFC will -be moved from `accepted/` to `implemented/`. +Implementation pull requests may be opened for review at any time, however please be sure to mark your pull requests as drafts until the implementation is complete and the ADR has been reviewed. The implementation pull request must also include a link to the ADR pull request. + +Pull requests containing ADRs will be reviewed within 2 weeks and assigned to the agenda of an upcoming RFC call to discuss the technical implementation. This review may also be repeated depending on feedback and questions. -If you'd like to implement an accepted RFC, please make a PR in the -appropriate repo and mention the RFC in the PR. Feel free to do this even -for work-in-progress code. The npm CLI team will provide guidance to -ensure that the patch meets our standards and addresses the proposed RFC. +After an ADR document is created, and implementation is complete and adheres to the decisions that have been documented, the pull request containing the ADR will be merged. We wait for implementation to be complete so that the ADR can be compared to the implementation at review time and we can ensure that the documentation related to the change is clear and accurate. ### Withdrawal -From time to time npm collaborators will review RFCs awaiting -implementation to ensure their accuracy and relevance. In cases where a -previously ratified RFC is deemed to no longer be a viable candidate for -implementation, an [**amendment section**](withdrawn/0000-template.md) will -be added **to the top** of the document outlining the reason for repeal and -subsequently moved to the `withdrawn/` section of this repository. +From time to time npm collaborators will review RFCs awaiting implementation to ensure their accuracy and relevance. In cases where a previously ratified RFC is deemed to no longer be a viable candidate for implementation, the RFC issue will be closed specifying the reason it is no longer applicable. + +If a proposal is withdrawn at the ADR phase, the ADR pull request and any incomplete implementation pull requests will also be closed citing the specific reason. If the reason is that the DRI is no longer available to oversee the implementation, rather than closing the existing pull requests the DRI will be unassigned and the "needs DRI" label will be added. At this point the feature is available for any other community member to volunteer to take over. ## How do I change an RFC after ratification? -RFCs themselves are typically only modified after ratification to address -unanswered questions that may require implementation exploration. +Put simply, you don't. The RFC is intended to convey an idea, not a specific means of creating or consuming the product of that idea. As such it should be somewhat rare for an RFC to change course after it has already been accepted. If this does happen, the npm team may elect to close the initial RFC as superseded by a new issue with a revised idea. -More often, if an RFC has been previously ratified, and either cannot be -implemented as described, or should be superceded by another proposal, it -will be withdrawn as part of another RFC submitted through this process. +An ADR, however, is meant to be a living document and may be edited as often as necessary until implementation is complete and relevant pull requests have been merged. ---