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 6 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
59 changes: 59 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,59 @@
### 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 same as the filename.*

## 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 **Thematic Roadmap** where possible]. Reference prior community discussions to demonstrate support for this RFC.*
Copy link

Choose a reason for hiding this comment

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

Link?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Clarifying - do you mean: 1) where's the link to the roadmap? 2) Link (instead of Reference) prior community discussions?

Copy link

Choose a reason for hiding this comment

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

number 1, it sounds like you want to link to a doc here...


### User Stories or Use Cases [optional]
Copy link
Contributor

Choose a reason for hiding this comment

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

I'd like to see this be required for RFCs that are driven by an enhancement that impacts users.

Copy link

Choose a reason for hiding this comment

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

I would make this not optional since I think it's important to explain who this is for (helps target folks for comments on the RFC as well)


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

### 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 or adaptations from earlier designs.*

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

172 changes: 172 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,172 @@
### DCP PR:

# RFC Process

## Summary

The Human Cell Atlas Data Coordination Platform (HCA DCP) evolved informal, consensus-driven processes to coordinate and document technical and governance decisions.
Copy link

Choose a reason for hiding this comment

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

I would remove "consensus-driven" and "egalitarian" from the former and latter sentences. I think that's the ideal we're going for, but in the early days of the DCP it was really a small group of people making reasonable choices within boxes given their understanding of the DCP.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

WFM. It was a direct quote from the white paper.


This early *lightweight* and *egalitarian* 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 consistent **Request for Comments (RFC)** process to propose enhancements to software or governance which are then maintained in a central repository.
Copy link
Member

Choose a reason for hiding this comment

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

I think there is a lack of clarity on what is meant by governance in this context. I think software is easier to intuit as presumably a software RFC would be about requesting significant new features or changes to our existing software stack or adding a significant piece of new software to the stack.

Governance is more nuanced so might need more spelling out.

I am certainly uncertain what might get an RFC from a governance perspective and what of our existing processes would need RFCs written about them so there is clarity on them from a community perspective.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Here are some examples of a Rust Governance RFC and Rust Roadmap based on this issue.

DCP PM can decide on topics for governance RFC(s).

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

@lauraclarke - I've added more detail about governance to the When is a RFC required? section:

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

Copy link

Choose a reason for hiding this comment

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

And here I'd say we're doing the RFC process to make our work process more "consensus-driven" and "egalitarian"....

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

WFM.


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

- To ensure consistency of the architectural design, senior technical leaders must monitor multiple work streams 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?

Any proposal that would benefit from additional review or design before being implemented is a good candidate for an RFC.

- An RFC is required if the implemented design would be described in written communication to the community.
- 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 if a technical initiative (refactoring, major architectural change) impacts the community.
Copy link

Choose a reason for hiding this comment

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

changing an interface...

- A 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-proposed" 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-proposed" and the "Governance" labels.
Copy link

Choose a reason for hiding this comment

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

again, consider at least a third RFC of type "informational" to move away from buried google docs to something that can act as a more formation communication mechanism...

Copy link
Collaborator Author

@brianraymor brianraymor Sep 24, 2018 •
edited
Loading

Choose a reason for hiding this comment

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

We have Informational RFCs at the IETF. I also reviewed the **Python Enhancement Process** (PEP) which is the origin of the Rust process and supports this type:

There are three kinds of PEP:

A Standards Track PEP describes a new feature or implementation for Python. It may also describe an interoperability standard that will be supported outside the standard library for current Python versions before a subsequent PEP adds standard library support in a future version.

An Informational PEP describes a Python design issue, or provides general guidelines or information to the Python community, but does not propose a new feature. Informational PEPs do not necessarily represent a Python community consensus or recommendation, so users and implementers are free to ignore Informational PEPs or follow their advice.

A Process PEP describes a process surrounding Python, or proposes a change to (or an event in) a process. Process PEPs are like Standards Track PEPs but apply to areas other than the Python language itself. They may propose an implementation, but not to Python's codebase; they often require community consensus; unlike Informational PEPs, they are more than recommendations, and users are typically not free to ignore them. Examples include procedures, guidelines, changes to the decision-making process, and changes to the tools or environment used in Python development. Any meta-PEP is also considered a Process PEP.

The question is how we would want to process Informational RFCs. Generally, they have a different workflow. Would it be simple editorial review? Would approval be required? What are your thoughts? Do you have a specific case in mind?

Created - Should Informational RFCs be supported? and added to the top-level summary comment.

Copy link

Choose a reason for hiding this comment

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

In the Commons we've used informational RFCs to communicate what a given working group has done over a 6 month period. For example, we have a working group on GUIDs. That group made an informational RFC that covered the different GUID types they explored, how they work, benefits, etc. And that was passed to other groups as a "here's what you need to know if you haven't been attending the call over the last 6 months"... it seems to be a very efficient communication mechanism. Since the stakes are lower for these, maybe the goal is to collect comments but, eventually, the RFC period ends and the informational RFC is just collected as a point of reference? There's no reason to build consensus per se since it's just reporting back information to other groups. I'm not sure but I think that could be helpful in the HCA project but maybe less so than in the Commons since there are fewer groups doing exploration work and needing to report back. It would be nice to have the informational RFC as an option, though, to have a framework to discuss items in a structured way.


- Share a link to the RFC pull request for community review on the HumanCellAtlas **#dcp** slack channel

#### 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 and add the "science-review-required" label.

#### Shepherd:
- Include the RFC submission in *This week in DCP* status update
Copy link

Choose a reason for hiding this comment

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

Link to this...

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Clarifying - Do you mean Link to this RFC submission in ...

Copy link

Choose a reason for hiding this comment

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

My understanding is "This Week in DCP" is a slack channel so reference that here...

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Rust and Kubernetes use a combination of a web site (similar to a blog) and a mail chimp list for subscribers. Science Governance may prefer an email message over monitoring a slack channel?


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

#### 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 a top-level summary comment in the RFC pull request. Replace "rfc-proposed" with "rfc-final-review".

- For software RFCs, share a link to the RFC pull request for approval on the HumanCellAtlas **#tech-architecture** slack channel. Add the RFC as an agenda item to the next *DCP Architecture* meeting.

- For governance RFCs, share a link to the RFC pull request for approval on the HumanCellAtlas **#dcp-project-mgmt** slack channel. Add the RFC as an agenda item to the next *DCP PM* meeting.

- Include the RFC final review in *This week in DCP* status update

### 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-final-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
- Include the RFC approval in *This week in DCP* status update
Copy link
Member

Choose a reason for hiding this comment

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

The this week in the DCP is a nice concept but new, where did it come from and is someone going to take ownership?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

It's borrowed from This Week in Rust and Last Week in Kubernetes. It's a scenario for @jodihir and @matthewspeir and the Communication team charter.

Copy link
Member

Choose a reason for hiding this comment

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

This sort of idea takes a lot of work. Before it goes into the approved document we need to ensure someone actually has time to do it. If no one will in the first instance then we should consider alternative solutions.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Agreed. Much can also be simply automated - https://github.com/cmr/this-week-in-rust.

Copy link

Choose a reason for hiding this comment

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

I really the weekly status update idea. I think it has come up before. I don't know that we'll be able to implement it first, but it would be great to do eventually.

Copy link

Choose a reason for hiding this comment

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

+1 to the weekly update via slack or email. That plus RFCs would be a very streamlined way to stay up to date on HCA without attending a ton of meetings


### 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-final-review" with "rfc-declined", and close the pull request with the rationale in the comment.

#### Shepherd:
- Include the RFC rejection in *This week in DCP* status update

#### Author:
- If an RFC is rejected by *DCP Architecture*, then the decision may be escalated for review by *DCP PM* by sending a request to the HumanCellAtlas **#dcp-project-mgmt** slack channel

### Unresolved questions

*What aspects of the design do you expect to clarify further through the RFC review process?*

There is a [pending issue](https://github.com/HumanCellAtlas/dcp-community/issues/25) to define how DCP might document when an approved RFC is implemented.

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