diff --git a/rfcs/rfc-template.md b/rfcs/rfc-template.md new file mode 100644 index 00000000..e28be7dc --- /dev/null +++ b/rfcs/rfc-template.md @@ -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/)` + +# 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?* + diff --git a/rfcs/text/0001-rfc-process.md b/rfcs/text/0001-rfc-process.md new file mode 100644 index 00000000..5855b146 --- /dev/null +++ b/rfcs/text/0001-rfc-process.md @@ -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. \ No newline at end of file