Skip to content

Commit

Permalink
feat: rewrite README to describe new rfc process
Browse files Browse the repository at this point in the history
  • Loading branch information
@nlf
nlf committed Mar 8, 2023
1 parent b1a427b commit 5ad83e6
Showing 1 changed file with 51 additions and 123 deletions.
174 changes: 51 additions & 123 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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.

---

Expand Down

0 comments on commit 5ad83e6

Please sign in to comment.