RFC Process #27
RFC Process #27
Conversation
brianraymor
requested review from
briandoconnor,
lauraclarke,
tburdett,
mweiden,
bkmartinjr and
TimothyTickle
rfcs/text/0000-rfc-process.md
Outdated
|
|
||
| ## Summary | ||
|
|
||
| The Human Cell Atlas Data Coordination Platform (HCA DCP) evolved informal, consensus-driven processes to coordinate and document technical decisions. |
There was a problem hiding this comment.
If there are also governance processes decided this probably needs to be changeed to "document technical and governance decisions"
rfcs/text/0000-rfc-process.md
Outdated
|
|
||
| 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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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).
There was a problem hiding this comment.
@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.
rfcs/text/0000-rfc-process.md
Outdated
| #### Reviewers: | ||
| - Add feedback to the pull request comment thread | ||
|
|
||
| #### Science Reviewer: |
There was a problem hiding this comment.
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.
rfcs/text/0000-rfc-process.md
Outdated
| - 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 |
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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).
There was a problem hiding this comment.
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
rfcs/text/0000-rfc-process.md
Outdated
| #### Shepherd: | ||
|
|
||
| - Validate that the RFC pull request was successfully updated and merged | ||
| - Include the RFC approval in *This week in DCP* status update |
There was a problem hiding this comment.
The this week in the DCP is a nice concept but new, where did it come from and is someone going to take ownership?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Agreed. Much can also be simply automated - https://github.com/cmr/this-week-in-rust.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
+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
rfcs/text/0000-rfc-process.md
Outdated
|
|
||
| ### Revising RFC(s) | ||
|
|
||
| How are RFC(s) maintained as *living documents* in an iterative development process where the original design may substantially change based on implementation experiences? |
There was a problem hiding this comment.
This question seemed slightly out of context. Is it motivating the subsequent sentence that defines the process? If so, should it be in the motivation section?
There was a problem hiding this comment.
It's a rhetorical device, but I take your point that it could simply be another case in motivations.
rfcs/text/0000-rfc-process.md
Outdated
|
|
||
| - **Approvers** for software RFC(s) are the Technical Leads from *DCP Architecture*. | ||
|
|
||
| - **Reviewers** are DCP community members. |
There was a problem hiding this comment.
Suggest clarifying that the DCP community includes both implementors and users of the DCP. In other words, RFCs affecting third-parties not affiliated with DCP implementation should also be welcomed as reviewers.
rfcs/text/0000-rfc-process.md
Outdated
|
|
||
| - Fill in the RFC with attention to detail | ||
|
|
||
| - Submit a pull request. |
There was a problem hiding this comment.
do you want the PR on a unique branch, or against master? Often useful to ask for a unique branch.
There was a problem hiding this comment.
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?
rfcs/rfc-template.md
Outdated
|
|
||
| # RFC Name | ||
|
|
||
| *This is the same as the filename* |
There was a problem hiding this comment.
nit: Add a period at the end of the sentence.
rfcs/rfc-template.md
Outdated
| - *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 / Limitations [optional] |
There was a problem hiding this comment.
suggest: ### Drawbacks and Limitations
rfcs/rfc-template.md
Outdated
| ### Alternatives [optional] | ||
|
|
||
| *Highlight other possible approaches to delivering the value proposed in this RFC. | ||
| What other designs were explored and what was the rationale for rejecting them?* |
There was a problem hiding this comment.
How about including the benefits of the alternatives as well? They should be presented in the best light.
There was a problem hiding this comment.
@mweiden - How about: 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 the alternatives?
rfcs/text/0000-rfc-process.md
Outdated
| - A RFC is required if a technical initiative (refactoring, major architectural change) impacts the community. | ||
| - A RFC is required for all changes to DCP governance. | ||
|
|
||
| ### Revising RFC(s) |
There was a problem hiding this comment.
nit: I'd just make this RFCs here and in other places in the document. For example, without the s, Revising RFC and Proposing RFC do not make sense.
https://english.stackexchange.com/questions/93940/number-agreement-when-using-s-for-optional-plural
There was a problem hiding this comment.
I'll ensure that there is consistent use of RFCs instead of RFC(s). And I'll correct all cases of a RFC to an RFC.
rfcs/text/0000-rfc-process.md
Outdated
| - Submit a pull request. | ||
|
|
||
| For software RFC(s): | ||
| - Add the "rfc-proposed" and the appropriate software project name _(such as "Data Store")_ labels. When the RFC crosses the scope of 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* |
There was a problem hiding this comment.
In context, this sentence is a little confusing: When the RFC crosses the scope of software projects, then the "Architecture" label **MUST** be the project name.
There was a problem hiding this comment.
@mweiden - Can you suggest an edit? How about: When the RFC is cross-cutting, then the "Architecture" label ... or When the RFC impacts multiple DCP software projects, ...
There was a problem hiding this comment.
I like your second example
rfcs/text/0000-rfc-process.md
Outdated
|
|
||
| - 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 pull request. Replace "rfc-proposed" with "rfc-final-review". | ||
|
|
||
| - For software RFC(s), share a link to the pull request for approval on the HumanCellAtlas **#tech-architecture** slack channel. Add the RFC as an agenda item to the next *DCP Architecture* meeting. |
There was a problem hiding this comment.
nit: this sentence, also, would not be grammatically correct with RFC in the singular.
rfcs/rfc-template.md
Outdated
|
|
||
| ## 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.* |
There was a problem hiding this comment.
Clarifying - do you mean: 1) where's the link to the roadmap? 2) Link (instead of Reference) prior community discussions?
There was a problem hiding this comment.
number 1, it sounds like you want to link to a doc here...
rfcs/rfc-template.md
Outdated
|
|
||
| *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.* | ||
|
|
||
| ### User Stories or Use Cases [optional] |
There was a problem hiding this comment.
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)
|
|
||
| *Why should this RFC **not** be implemented?* | ||
|
|
||
| ### Prior Art [optional] |
There was a problem hiding this comment.
Maybe add to this section or on it's own a section for Community Standards?
There was a problem hiding this comment.
I would add to this section since Community Standards fits the criteria.
rfcs/text/0000-rfc-process.md
Outdated
|
|
||
| ## Summary | ||
|
|
||
| The Human Cell Atlas Data Coordination Platform (HCA DCP) evolved informal, consensus-driven processes to coordinate and document technical and governance decisions. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
WFM. It was a direct quote from the white paper.
rfcs/text/0000-rfc-process.md
Outdated
|
|
||
| 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. |
There was a problem hiding this comment.
And here I'd say we're doing the RFC process to make our work process more "consensus-driven" and "egalitarian"....
rfcs/text/0000-rfc-process.md
Outdated
|
|
||
| - **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*. |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
Approval is not based on voting but consensus. I would expect the other PMs or Technical Leads would review appropriately.
rfcs/text/0000-rfc-process.md
Outdated
|
|
||
| For governance RFCs: | ||
|
|
||
| - Add the "rfc-proposed" and the "Governance" labels. |
There was a problem hiding this comment.
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...
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
rfcs/text/0000-rfc-process.md
Outdated
| - 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 |
There was a problem hiding this comment.
Clarifying - Do you mean Link to this RFC submission in ...
There was a problem hiding this comment.
My understanding is "This Week in DCP" is a slack channel so reference that here...
There was a problem hiding this comment.
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?
rfcs/text/0000-rfc-process.md
Outdated
|
|
||
| - Include the RFC final review in *This week in DCP* status update | ||
|
|
||
| ### Approving RFCs |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
@tburdett has opened an issue for timeboxes for all processes which I've added to the top-level summary comment under Open Issues.
rfcs/text/0000-rfc-process.md
Outdated
| #### Shepherd: | ||
|
|
||
| - Validate that the RFC pull request was successfully updated and merged | ||
| - Include the RFC approval in *This week in DCP* status update |
There was a problem hiding this comment.
+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
|
I mainly left comments but "requested changes" in my review. I'm happy to approve once you've taking a look at my comments even if you decide not to implement changes. |
There was a problem hiding this comment.
I'm happy with all of the process part here, but I think the "When is an RFC required?" section could use some clarification.
I've added comments inline, but currently I see three main challenges:
- Feature requests from users of the DCP (not users of components of the DCP) are hard to capture in a way that supports DCP wide planning
- A large amount of ad-hoc development means we have poorly understood interactions between projects, sometimes containing flawed assumptions
- Planning a path from the current situation to a desired or designed goal is difficult, especially when this touches multiple projects
To provide a specific example, myself and @mweiden have been discussing two overlapping docs around how to ensure datastore and ingest clients use the metadata schema in a sustainable way. I have written a doc clarifying the framework within which clients should operate, @mweiden has written a development roadmap proposing a path to an improved situation. Both of these are required technical docs but arguably neither should impact DCP users. Both could fit the RFC process.
I think there are two options -
- We reserve the RFC process for design changes that propose new functionality or modify the design in ways that have user-facing impact, and use some other process (github issues plus better docs in repos?) for other modifications
- We use RFCs for the three different scenarios (roughly, enhancements, framework/contract definitions, implementation roadmaps) and declare a type for clarity.
This is very much a discussion topic, but I shall mark this as "request changes", because I think the minimum required is to clarify that the RFC process is for user-impacting design changes. There was slightly more specific text in the Technical Decision-making document that covered this quite well.
rfcs/rfc-template.md
Outdated
|
|
||
| *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.* | ||
|
|
||
| ### User Stories or Use Cases [optional] |
There was a problem hiding this comment.
I'd like to see this be required for RFCs that are driven by an enhancement that impacts users.
rfcs/text/0000-rfc-process.md
Outdated
|
|
||
| ### 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). |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.
September 25: Reviewed at DCP PM F2F meeting. Approved with changes.
Issues that were addressed:
November 15: Approved during DCP PM call
Tracking issues for future revisions of the RFC process - also noted in the Unresolved Questions section in the RFC: