Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: document RFC final comment period guidelines #10181

Merged
merged 1 commit into from Oct 24, 2016
Merged

docs: document RFC final comment period guidelines #10181

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
40 changes: 26 additions & 14 deletions docs/RFCS/README.md
View file
Open in desktop
Expand Up @@ -11,18 +11,32 @@ This is a lightweight design-document process that is inspired by the

1. Copy `template.md` to a new file and fill in the details. Commit
this version in your own fork of the repository or a branch.

2. Submit a pull request to add your new file to the main repository.
Each RFC should get its own pull request; do not combine RFCs with
other files.

3. Go through the PR review. If there is consensus to proceed with the
project, change the `Status` field of the document to
`in-progress`, update the `RFC PR` field, and merge the PR. If the
project is rejected, either abandon the PR or merge it with a
status of `rejected` (depending on whether the document and

3. Go through the PR review. When the dust on the PR review has settled,
and if there is consensus to proceed with the project, begin the
final comment period (FCP) by (1) posting a comment on the PR and
(2) posting an announcement on the persistent public communication
channel du jour (https://forum.cockroachlabs.com/ at the time of
this writing).
The FCP should last a minimum of two working days to allow
collaborators to voice any last-minute concerns. If there is still
consensus to proceed after the FCP, change the `Status` field of the
document to `in-progress`, update the `RFC PR` field, and merge the
PR. If the project is rejected, either abandon the PR or merge it
with a status of `rejected` (depending on whether the document and
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Might be worth mentioning that accepted RFCs can hit snags during implementation that could have been caught during the RFC review process. This is undesirable and something we should try to avoid, but hard to eliminate completely unless we make the RFC process overly onerous. For example, what happens if an expert on part of the system is on an extended vacation when an RFC is being reviewed?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What would be the purpose of such a mention? In other words, what is the guidance being issued to the reader, when they encounter such a case?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The purpose would be to set expectations: an accepted RFC is not an immutable contract. We can back out of them.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done, PTAL.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

discussion are worth preserving for posterity).

Note that it is possible for an RFC to receive discussion after it
has been approved and its PR merged, e.g. during implementation.
While this is undesirable and should generally be avoided, such
discussion should still be addressed by the initiator (or
implementer) of the RFC. For instance, this can happen when an
expert is not available during the initial review (e.g. because she
is on vacation).

4. Once the changes described in the RFC have been made, change the
status of the PR from `in-progress` to `completed`. If subsequent
developments render an RFC obsolete, set its status to `obsolete`.
Expand All @@ -35,13 +49,13 @@ other RFCs or PRs that make it obsolete.
During its lifetime an RFC can have the following status:

- Draft

A newly minted RFC has this status, until either the proposal is
accepted (next possible status: in-progress) or that it is DOA (next
possible status: rejected).

- In-progress

A RFC receives this status when the PR discussions have concluded
the proposal should be implemented, and the RFC is ready to commit
(merge) to the main repository.
Expand All @@ -51,14 +65,12 @@ During its lifetime an RFC can have the following status:
subsequent work removes the need for the feature).

- Completed

A RFC receives this status when the described feature has been
implemented. It may stay with this status indefinitely or until made
obsolete.

- Obsolete

A RFC receives this status when the described feature has been
superseded.