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

RFC Process #27

Merged
merged 20 commits into from
Nov 15, 2018
Merged

RFC Process #27

Show file tree
Hide file tree
Changes from 19 commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
a6a90bd
RFC Process
brianraymor Sep 13, 2018
64aca30
Editorial changes based on Matt's feedback
brianraymor Sep 18, 2018
6541b2b
Editorial 'RFC' references
brianraymor Sep 19, 2018
2513ba3
Addressed Laura's feedback in Summary
brianraymor Sep 19, 2018
9d05b0b
Editorial - feedback
brianraymor Sep 19, 2018
3bf89ef
Added more detail on governance RFCs
brianraymor Sep 19, 2018
ad83db5
Updates from reviews
brianraymor Oct 2, 2018
2c52e63
Updates from reviews
brianraymor Oct 2, 2018
a20dc57
Update RFC labels
brianraymor Oct 19, 2018
49b3af0
oversight review is limited to approvers
brianraymor Oct 19, 2018
7ac174a
substantial changes during oversight review
brianraymor Oct 19, 2018
debbe33
Remove This week in DCP
brianraymor Oct 19, 2018
324ba31
Added time boxes
brianraymor Oct 19, 2018
0e8e965
Appealing RFC decisions
brianraymor Oct 19, 2018
cdc29f1
Editorial updates
brianraymor Oct 19, 2018
0d208c2
Updated Unresolved questions
brianraymor Oct 19, 2018
4a71055
Clarifying author role in change requests by approvers
brianraymor Oct 19, 2018
4dca0a3
Added #dcp channel announcements for oversight decisions
brianraymor Oct 19, 2018
edb8fdb
Editorial updates for consistent style
brianraymor Oct 19, 2018
61453a5
Final edits for RFC approval
brianraymor Nov 15, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 65 additions & 0 deletions rfcs/rfc-template.md
View file
Open in desktop
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:[email protected])`

## 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:[email protected])`

## 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]
tburdett marked this conversation as resolved.
Show resolved Hide resolved

*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]
Copy link

Choose a reason for hiding this comment

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

Maybe add to this section or on it's own a section for Community Standards?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

I would add to this section since Community Standards fits the criteria.

Copy link

Choose a reason for hiding this comment

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

OK


*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?*

237 changes: 237 additions & 0 deletions rfcs/text/0000-rfc-process.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,237 @@
### DCP PR:

# 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]([email protected])

## 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*.

Copy link

Choose a reason for hiding this comment

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

I would add another reason, for box/project leadership there is no formal way of tracking major feature decision making process. What I mean by that is, if I want to keep up with say blue box, I need to minimally attend the sprint planning and demo meetings, backlog grooming, architects meeting, and then keep up to date on multiple slack channels. By moving an important decisions/features to RFCs I know, as a box lead, I can read the RFCs and see the most important discussions in a single place. This hugely streamlines the "n x n" information problem in large projects like HCA (where everyone feels like they need to communicate with all other folks on the project via meetings/slacks/emails in order to stay "on top" of the project but ultimately don't get work done because they've spent all their time communicating). With teams leaning into RFCs for any significant interface/feature designs, it will greatly streamline information flow in the project. At least I think this will be true.

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).
Copy link
Contributor

Choose a reason for hiding this comment

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

This still feels a little bit open to interpretation to me. I like this quote from the Rust RFC readme:

Some changes though are "substantial", and we ask that these be put through a bit of a design process and produce a consensus among the Rust community and the sub-teams.

Whilst you have the "substantial" part, and this is clear, the additional context in the Rust doc ("put through a bit of a design process") helps make it clear to me that this is a design proposal rather than an implementation plan. Is the intention here that RFCs are lightweight design documents, or might you have RFCs proposing an implementation plans?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

An RFC does not propose an "implementation plan" based on the constraint from the white paper which is captured in the RFC process:

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.

My thought is that an RFC offers a detailed design. IF implemented, the design may change. At that point, the RFC should be updated to reflect reality - similar to WHATWG living standards. Requires some discipline. Does this clarify?

Copy link
Contributor

Choose a reason for hiding this comment

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

My thoughts were definitely the same as yours. I was observing that "technical decisions" and "changes to system behaviour" could be open to a wide range of interpretations, and not necessarily just limited to design. However, I'm also prepared to believe I'm looking to be over-prescriptive given that my own interpretation was consistent with the intent.


**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.
Copy link

Choose a reason for hiding this comment

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

In another project I'm working on there are distinct types of RFCs... some for interfaces, others for process, and others still as "informational". I'm wondering if we need something similar here? It ends up giving more flexibility for using RFCs as a formal communication process and not just an API design feedback process...


- 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).

tburdett marked this conversation as resolved.
Show resolved Hide resolved
### 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*.
Copy link

Choose a reason for hiding this comment

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

approvers cannot be the author of the RFC? I'm just wondering if an architect writes an RFC for his or her box, he or she should not be the approver of the RFC, right?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Approval is not based on voting but consensus. I would expect the other PMs or Technical Leads would review appropriately.


- **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.
Copy link

Choose a reason for hiding this comment

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

do you want the PR on a unique branch, or against master? Often useful to ask for a unique branch.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

I don't have a strong opinion. Neither PEP nor Rust have such a requirement. We could suggest but would we really want to enforce?


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:
Copy link
Member

Choose a reason for hiding this comment

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

From a process perspective we need to make sure that RFCs that require scientific review don't get bottlenecked through one or a limited number of people. Doesn't necessarily change this document but worth thinking about.

- 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
Copy link

Choose a reason for hiding this comment

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

I think I might have missed it but is there a timing element here? Like review needs to wrap up in X weeks? I've noticed in other projects I'm working on the RFCs are just building up because there's not fixed schedule to comment on them and then finalize them.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

@tburdett has opened an issue for timeboxes for all processes which I've added to the top-level summary comment under Open Issues.


#### 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
Copy link
Member

Choose a reason for hiding this comment

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

I am going to guess no heavyweight solution is needed to this as we are unlikely to have a lot of RFCs which are in review concurrently (at least after the first batch to document our existing design) but do we need to do anything to guard against two people committing at the same time using the same RFC number

Copy link

Choose a reason for hiding this comment

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

Given that github will ensure they are unique and differentiated changes to the rep, it is easy to fix collisions after they occur (by assigning one of the RFCs a new ID). This should be a Shepherd responsibility (or whomever does the PR merge).

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

There's also a step in the process for the Shepherd to validate the changes:

Validate that the RFC pull request was successfully updated and merged


- 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 ([email protected]).

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
brianraymor marked this conversation as resolved.
Show resolved Hide resolved

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.