-
Notifications
You must be signed in to change notification settings - Fork 18
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #27 from brianraymor/rfc-process
Approved DCP RFC Process
- Loading branch information
Showing
2 changed files
with
304 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,65 @@ | ||
| ### DCP PR: | ||
|
|
||
| ***Leave this blank until the RFC is approved** then the **Author(s)** must create a link between the assigned RFC number and this pull request in the format:* | ||
|
|
||
| `[dcp-community/rfc#](https://github.com/HumanCellAtlas/dcp-community/pull/<PR#>)` | ||
|
|
||
| # RFC Name | ||
|
|
||
| *This is the name of the RFC. Keep it short and descriptive.* | ||
|
|
||
| ## Summary | ||
|
|
||
| *Describe the vision of the RFC in 2-3 sentences. Consider this section as your "elevator pitch" or "release note" to the community.* | ||
|
|
||
| ## Author(s) | ||
|
|
||
| *Recommended format for Authors:* | ||
|
|
||
| `[Name](mailto:username@example.com)` | ||
|
|
||
| ## Shepherd | ||
| ***Leave this blank.** This role is assigned by DCP PM to guide the **Author(s)** through the RFC process.* | ||
|
|
||
| *Recommended format for Shepherds:* | ||
|
|
||
| `[Name](mailto:username@example.com)` | ||
|
|
||
| ## Motivation | ||
|
|
||
| *Describe the user or technical need in detail [with alignment to the DCP roadmap priorities where possible]. Link prior community discussions to demonstrate support for this RFC.* | ||
|
|
||
| ### User Stories | ||
|
|
||
| *Share the [User Stories](https://www.mountaingoatsoftware.com/agile/user-stories) motivating this RFC.* | ||
|
|
||
| ## Scientific "guardrails" [optional] | ||
|
|
||
| *Describe recommended or mandated review from HCA Science governance to ensure that the RFC addresses the needs of the scientific community.* | ||
|
|
||
| ## Detailed Design | ||
|
|
||
| *Explain the design in sufficient detail such that the implementation and (if appropriate) the interaction with existing DCP software are both reasonably clear.* | ||
|
|
||
| ### Acceptance Criteria [optional] | ||
|
|
||
| *Acceptance criteria are the conditions that a RFC must satisfy to be accepted by users or other stakeholders.* | ||
|
|
||
| ### Unresolved Questions | ||
|
|
||
| - *What aspects of the design do you expect to clarify further through the RFC review process?* | ||
| - *What aspects of the design do you expect to clarify later during iterative development of this RFC?* | ||
|
|
||
| ### Drawbacks and Limitations [optional] | ||
|
|
||
| *Why should this RFC **not** be implemented?* | ||
|
|
||
| ### Prior Art [optional] | ||
|
|
||
| *Share references to prior art to deepen community understanding of the RFC, such as learnings, adaptations from earlier designs, or community standards.* | ||
|
|
||
| ### Alternatives [optional] | ||
|
|
||
| *Highlight other possible approaches to delivering the value proposed in this RFC. | ||
| What other designs were explored? What were their advantages? What was the rationale for rejecting alternatives?* | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,239 @@ | ||
| ### DCP PR: | ||
|
|
||
| [dcp-community/rfc1](https://github.com/HumanCellAtlas/dcp-community/pull/27) | ||
|
|
||
| # RFC Process | ||
|
|
||
| ## Summary | ||
|
|
||
| The Human Cell Atlas Data Coordination Platform (HCA DCP) evolved informal processes to coordinate and document technical and governance decisions. | ||
|
|
||
| This early *lightweight* approach enabled the DCP to achieve rapid velocity and incorporate a diverse set of innovative design concepts. | ||
|
|
||
| As DCP continues to mature and scale, our community can more easily contribute and learn when there is a formal and consensus-driven **Request for Comments (RFC)** process to propose enhancements to software or governance which are then maintained in a central repository. | ||
|
|
||
| ## Author(s) | ||
| *DCP PM* | ||
|
|
||
| **NOTE:** *This proposal is based on ideas from the **HCA DCP Technical Decision-Making** white paper written by Bruce Martin with contributions from Tony Burdett, Laura Clarke, Brian O’Connor, Brian Raymor, and Tim Tickle.* | ||
|
|
||
| ## Shepherd | ||
| [Brian Raymor](brianraymor@chanzuckerberg.com) | ||
|
|
||
| ## Motivation | ||
|
|
||
| There are a number of limitations with our current process which need to be addressed: | ||
|
|
||
| - For community members who want to propose enhancements to either technical software or governance, it is often unclear where to start - *for example, which HCA slack channel or project member to approach with a proposal.* | ||
|
|
||
| - There is no common template for design proposal submissions. | ||
|
|
||
| - There is no common process describing how the community reviews and approves submitted proposals. | ||
|
|
||
| - There is no formal assistance to guide a contributor through the process. | ||
|
|
||
| - New community members experience difficulties when _onboarding_. There is no curated repository of up-to-date design documents to assist with learning about the software. | ||
|
|
||
| - Members cannot easily follow the decision making process for major features. | ||
|
|
||
| To ensure consistency of the architectural design, senior technical leaders must monitor multiple work streams which is time consuming, or hope that they are notified of potential technical changes - *this is a significant concern for cross-cutting issues such as security or the data model*. | ||
|
|
||
| To address these needs, the DCP RFC process defines a transparent and standard method for community members to propose and build consensus around substantial enhancements to DCP software or governance. | ||
|
|
||
| ### When is an RFC required? | ||
|
|
||
| - An RFC is required for **substantial** additions, deletions, or changes to system behavior or semantics (API, major features, data model, protocols, service guarantees, architecture). In [semver](https://semver.org/) terms, *major* changes require an RFC, while *minor* changes are often candidates (new API addition). | ||
|
|
||
| **NOTE**: *Internal-only implementation decisions, bug fixes, refactoring, and performance optimization are not substantial changes and can continue to be documented and tracked using github issues.* | ||
|
|
||
| - An RFC is required if a design impacts multiple DCP projects. | ||
|
|
||
| - An RFC is required for all changes to the DCP formal governance, including but not limited to oversight, decision-making, conflict resolution, and community processes such as charters and RFCs. For more background on governance, see the **Model C: Delegated Governance** section in [Organization & Structure of Open Source Software Development Initiatives](https://dash.harvard.edu/bitstream/handle/1/30805146/2017-03-24_governance.pdf). | ||
|
|
||
| ### Revising RFCs | ||
|
|
||
| Where necessary, existing RFCs can be revised using the same process (a proposed change submitted as a RFC pull request and subject to community review and approval). **Major changes should result in a new RFC.** | ||
|
|
||
| ### What are the roles in the RFC process? | ||
|
|
||
| - **Authors** are DCP community members. | ||
|
|
||
| - **Shepherds** are members of *DCP PM* assigned to assist the **Author(s)** and ensure that the RFC progresses to closure. | ||
|
|
||
| - **Approvers** for governance RFCs are the Project Leads and Product Owners from *DCP PM*. | ||
|
|
||
| - **Approvers** for software RFCs are the Technical Leads from *DCP Architecture*. | ||
|
|
||
| - **Reviewers** are DCP community members, including both software developers and users. | ||
|
|
||
| - **Science Reviewer** is the *DCP Science PM* in coordination with *HCA Science Governance*. | ||
|
|
||
| ## Detailed Design | ||
|
|
||
| ### Proposing RFCs | ||
|
|
||
| #### **Authors**: | ||
|
|
||
| *Before proposing, always engage the DCP community to build consensus and assess whether your proposal sparks interest and addresses a need. You may even discover potential collaborators.* | ||
|
|
||
| - Fork the HumanCellAtlas dcp-community repository | ||
| - Copy `rfcs/rfc-template.md` to `rfcs/text/0000-my-feature.md` | ||
| *- where "my-feature" is descriptive. Don't assign an RFC number yet.* | ||
|
|
||
| - Fill in the RFC with attention to detail | ||
|
|
||
| - Submit a pull request. | ||
|
|
||
| For software RFCs: | ||
| - Add the "rfc-community-review" and the appropriate software project name _(such as "Data Store")_ labels. When the RFC impacts multiple DCP software projects, then the "Architecture" label **MUST** be the project name. *If uncertain about the appropriate project name, then **_Ask a PM_** on the HCA **#dcp-project-mgmt** slack channel* | ||
|
|
||
| For governance RFCs: | ||
|
|
||
| - Add the "rfc-community-review" and the "Governance" labels. | ||
|
|
||
| - Add a minimum two week _last call_ for the completion of the Community review to the top-level summary comment in the RFC pull request. | ||
|
|
||
| **EXAMPLE** | ||
|
|
||
| **April 1**: Last call for community review | ||
|
|
||
| - Request a Community review of the RFC on the HumanCellAtlas **#dcp** slack channel. Include a link to the RFC pull request and the last call deadline: | ||
|
|
||
| **EXAMPLE** | ||
|
|
||
| ***@channel**: Call for community review of the RFC process - https://github.com/HumanCellAtlas/dcp-community/pull/27 - Last call is April 1.* | ||
|
|
||
| #### DCP PM: | ||
| - Assign a **Shepherd** by completing the *Shepherd* section in the RFC template and pushing the commit. The **Shepherd** guides the RFC and its **Author(s)** through the process. | ||
|
|
||
| - If there is a *Scientific "guardrails"* section in the RFC: | ||
| - Assign the **Science Reviewer** as a reviewer of the pull request | ||
| - Add the "science-review-required" label | ||
| - Add a two week _last call_ for the completion of the Science review to the top-level summary comment in the RFC pull request. | ||
|
|
||
| **EXAMPLE** | ||
|
|
||
| **April 5**: Last call for science review | ||
|
|
||
| **NOTE**: *The Science review occurs in parallel to the Community review.* | ||
|
|
||
| ### Reviewing RFCs | ||
|
|
||
| #### Approvers: | ||
| - May assign specific reviewers in the RFC pull request | ||
|
|
||
| #### Reviewers: | ||
| - Add feedback to the RFC pull request comment thread | ||
|
|
||
| #### Science Reviewer: | ||
| - When the feedback from the Science review is addressed, replace the "science-review-required" label with "science-review-completed". | ||
|
|
||
| #### Author: | ||
| - Revise the RFC pull request in response to feedback and push new commits | ||
|
|
||
| ### Shepherding RFCs | ||
| [Shepherding RFCs]: #shepherding-rfcs | ||
| #### Shepherd: | ||
| - Monitor the community review and ensure that issues are addressed by the **Author(s)** in a reasonable time period. | ||
|
|
||
| - When all issues are addressed and any required Science reviews are complete: | ||
| - Summarize the review discussion for the **Approvers** in the top-level summary comment in the RFC pull request | ||
| - Add a minimum one week _last call_ for the completion of the Oversight review to the top-level summary comment in the RFC pull request. | ||
|
|
||
| **EXAMPLE** | ||
|
|
||
| ~~**April 1**: Last call for community review~~ | ||
|
|
||
| **April 22**: Last call for oversight review | ||
|
|
||
| - Replace "rfc-community-review" with "rfc-oversight-review" | ||
|
|
||
| **NOTE**: *Oversight review is limited to **Approvers**. Further community reviews during this period may be disregarded by the **Author(s)**.* | ||
|
|
||
| - For software RFCs, request an Oversight review of the RFC on the HumanCellAtlas **#tech-architecture** slack channel. Include a link to the RFC pull request and the last call deadline | ||
|
|
||
| Add the RFC as an agenda item to the next *DCP Architecture* meeting | ||
|
|
||
| - For governance RFCs, request an Oversight review of the RFC on the HumanCellAtlas **#dcp-project-mgmt** slack channel. Include a link to the RFC pull request and the last call deadline: | ||
|
|
||
| **EXAMPLE** | ||
|
|
||
| ***@channel**: Call for oversight review of the RFC process - https://github.com/HumanCellAtlas/dcp-community/pull/27 - Last call is April 22.* | ||
|
|
||
| Add the RFC as an agenda item to the next *DCP PM* meeting | ||
|
|
||
| ### Approving RFCs | ||
|
|
||
| #### Approvers: | ||
|
|
||
| - At the *DCP PM* or *DCP Architecture* meeting, review the **Shepherd** summary. If there is rough consensus to approve the RFC, replace "rfc-oversight-review" with "rfc-approved" | ||
|
|
||
| #### Author(s): | ||
| - Rename the RFC from `0000-my-feature.md` to `rfc####-my-feature.md` (with leading zeros) where `####` is the next available RFC number | ||
|
|
||
| - Create a link between the approved RFC and its pull request by updating the *DCP PR* section in the RFC template and pushing the commit. | ||
|
|
||
| - Merge the RFC pull request | ||
|
|
||
| **NOTE**: *The existence of an approved software RFC does not indicate any particular priority or commitment to implement the RFC, nor is an approved RFC a green light to implement. Approved RFCs simply demonstrate community agreement on a technical decision. Product priorities are managed and implementations scheduled via the DCP PM planning process.* | ||
|
|
||
| #### Shepherd: | ||
|
|
||
| - Validate that the RFC pull request was successfully updated and merged | ||
|
|
||
| - Announce the approval of the RFC on the HumanCellAtlas #dcp slack channel. Include a link to the merged RFC: | ||
|
|
||
| **EXAMPLE** | ||
|
|
||
| ***@channel**: DCP PM approved the RFC for the RFC Process - https://github.com/HumanCellAtlas/dcp-community/rfcs/blob/master/text/0001-rfc-process.md* | ||
|
|
||
| ### Requesting substantive changes | ||
|
|
||
| #### Approvers: | ||
|
|
||
| - At the *DCP PM* or *DCP Architecture* meeting, review the **Shepherd** summary. If substantial changes are requested, then replace "rfc-oversight-review" with "rfc-community-review". | ||
|
|
||
| #### Authors: | ||
|
|
||
| - The **Author(s)** must address the changes before requesting a community review and returning the RFC to the [community review](#shepherding-rfcs) process. | ||
|
|
||
| ### Rejecting RFCs | ||
|
|
||
| #### Approvers: | ||
|
|
||
| - At the *DCP PM* or *DCP Architecture* meeting, review the **Shepherd** summary. If there is rough consensus to reject the RFC, replace "rfc-oversight-review" with "rfc-declined", and close the pull request with the rationale in the comment. | ||
|
|
||
| #### Shepherd: | ||
|
|
||
| - Announce the rejection of the RFC on the HumanCellAtlas #dcp slack channel. Include a link to the RFC pull request: | ||
|
|
||
| **EXAMPLE** | ||
|
|
||
| ***@channel**: DCP PM declined the RFC for the RFC Process - https://github.com/HumanCellAtlas/dcp-community/pull/27* | ||
|
|
||
| ### Appealing RFC Decisions | ||
|
|
||
| Any DCP community member may appeal all RFC decisions by **Approvers** (approval, changes requested, or rejection) by sending a message to the *DCP PM* mailing list (pm-team@data.humancellatlas.org). | ||
|
|
||
| The message should demonstrate a clear rationale for the appeal, referencing community discussion as needed to support the position. | ||
|
|
||
| *DCP PM* must review the appeal, resolve it in a manner of its own choosing, and respond to the original message on the *DCP PM* mailing list within two weeks. | ||
|
|
||
| ### Unresolved questions | ||
|
|
||
| *What aspects of the design do you expect to clarify later during iterative development of this RFC?* | ||
|
|
||
| - [Adding Informational RFCs](https://github.com/HumanCellAtlas/dcp-community/issues/30) | ||
| - [Tracking the implementation state of approved RFCs](https://github.com/HumanCellAtlas/dcp-community/issues/25) | ||
| - [Improving community notifications for RFCs](https://github.com/HumanCellAtlas/dcp-community/issues/37) | ||
|
|
||
| ### Drawbacks / Limitations | ||
|
|
||
| The dependence on Git and GitHub in the RFC process may be a barrier to potential contributors, but this is mitigated by the availability of the **Shepherd**. | ||
|
|
||
| ## Prior Art | ||
|
|
||
| The DCP RFC process is _inspired_ by and _adapted_ from [Rust](https://github.com/rust-lang/rfcs) | ||
| and [Kubernetes](https://kubernetes.io/docs/community/keps/). | ||
|
|
||
| The Internet Engineering Task Force assigns a [**Shepherd**](https://tools.ietf.org/html/rfc4858#section-3.1) during the _endgame_ of their standards process. |