Proposing changes/updates to the RFC process. #109
Conversation
|
It seems that this is an update of 0001-rfc-process.md rather than a new RFC. I think it would be easier to review and far more useful in the long term if this was just a PR with modifications of 0001-rfc-process.md. Having to read through two documents to understand the RFC process would no be optimal. |
|
@diekhans I think we (or perhaps maybe just I) would like to provide justification first on why these changes are being proposed in the first place prior to making direct amendments to the original RFC MD file since they are numerous enough. |
|
@maniarathi , I love having the rationale explicit rather than mind-reading. However, I am not sure having the rationale as a separate RFC is very useful. What happens when this PR is approved? Does the RFC-0001 get modified, then it goes through the old approval process? Does this PR stay around as a separate RFC or is this one deleted? I feel a draft PR on 0001 with only the rational discussed would be a less confusing approach. |
|
@diekhans Ah ok, I understand your perspective. For now, let me pause on the conversation and once Dave and I finish writing, we shall figure out how to proceed with the actual process of approval. For now, this PR is a draft (i.e. this is our "Google Doc" draft) so once we finish writing, we'll see how to proceed. |
|
@maniarathi at least I find this, as opposed to lost in google docs ;-) |
maniarathi
changed the title
|
How about "proposed RFC" rather than "pre-RFC"? I think that is clearer.
David Rogers <notifications@github.com> writes:
… NoopDog commented on this pull request.
> @@ -65,7 +65,9 @@ Additionally, with the encouraged behavior of submitting draft pull requests pri
We propose adding the following new tags:
-**pre-rfc-draft** : This indicates that the authors are still actively working on the RFC, that the RFC is in a draft state, and readers should **not** comment on the RFC yet. Additionally this state serves to indicate more clearly the backlog of RFCs in development to avoid duplication of effort of overlapping RFCs and to help elicit offers of co-authorship.
+**pre-rfc-draft** : This indicates that the authors are still actively working on the RFC, that the RFC is in a draft state, and readers should **not** comment on the RFC yet.
+
Hi @diekhans the intent here is to create a one stop shop for folks to see the backlog of rfcs that are currently being drafted. Folks can always keep whatever private docs or working groups they like if they prefer to work in secret.
Here we merely propose a formal way to optionally announce that the pre-rfc exists and that at the least describes the problem being addressed so that an interested party can contact the author(s) to discuss. Does adding "optional" to the text address your concerns?
--
You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub:
#109 (comment)
@NoopDog commented on this pull request.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
In rfcs/text/0000-rfc-process-updates.md:
> @@ -65,7 +65,9 @@ Additionally, with the encouraged behavior of submitting draft pull requests pri
We propose adding the following new tags:
-**pre-rfc-draft** : This indicates that the authors are still actively working on the RFC, that the RFC is in a draft state, and readers should **not** comment on the RFC yet. Additionally this state serves to indicate more clearly the backlog of RFCs in development to avoid duplication of effort of overlapping RFCs and to help elicit offers of co-authorship.
+**pre-rfc-draft** : This indicates that the authors are still actively working on the RFC, that the RFC is in a draft state, and readers should **not** comment on the RFC yet.
+
Hi @diekhans the intent here is to create a one stop shop for folks to see the
backlog of rfcs that are currently being drafted. Folks can always keep
whatever private docs or working groups they like if they prefer to work in
secret.
Here we merely propose a formal way to optionally announce that the pre-rfc
exists and that at the least describes the problem being addressed so that an
interested party can contact the author(s) to discuss. Does adding "optional"
to the text address your concerns?
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub, or mute the thread.*
|
maniarathi
changed the title
|
Not sure I agree with dropping oversight review completely, maybe shorten it to a few days. As you point out the community review is for science community members to be able to comment, if this is formalized, how will internal comments be accommodated? |
|
My personal experience with writing RFCs is that the process places an excessive burden on the author and/or shepherd 🐑. The biggest improvement in my estimation would be to minimize this process burden. I think we should either automate the process, or make it part of someone's job to help shepherd all the RFCs/update their status/post notices. The current level of effort required to see an RFC through to completion discourages and disincentivizes the use of RFCs for technical architecture discussion. The second biggest improvement, I think, is to discourage "bikeshedding" comments that don't add to the discussion or don't propose an alternative solution. I think people who don't spend a majority of their time as implementers should be discouraged from making such comments on technical RFCs. (I recognize that it's hard to write this down as a process rule - perhaps something about what kinds of comments the author is required to address to achieve consensus for the purpose of advancing the RFC). @brianraymor adds And if you're not familiar with the term - bikeshed. |
|
|
||
| We propose removing Oversight review altogether. A two week minimum community review period still exists but the | ||
| "community" refers to all members of the DCP working on any of the chartered organizations instead of the scientific | ||
| community only. This largely reflects the behavior of the review process today. |
There was a problem hiding this comment.
Again, this statement is incorrect.
There was a problem hiding this comment.
Will correct once I get confirmation about the definition :)
| We propose that, in order to ensure that RFCs are created based on critical tickets that are prioritized based on | ||
| the quarterly and yearly roadmaps and ensure that RFCs are followed up to completion, that all | ||
| [*non-informational RFCs*](https://github.com/HumanCellAtlas/dcp-community/issues/30) be linked to an existing Zenhub | ||
| ticket. Such a ticket should be linked to a timeline for RFC completion. |
There was a problem hiding this comment.
Tracked in Tracking the implementation state of an RFC and more recently RFC(s) should reference related Roadmap Objectives in ZenHub
| ## Motivation | ||
|
|
||
| Over the last year since the original RFC process was accepted, the DCP project has grown both in size and complexity. | ||
| As of this writing, 11 RFCs have been accepted in addition to many charters. Not so unexpectedly, there have been pain |
There was a problem hiding this comment.
Not sure what charters has to do with the RFC process.
There was a problem hiding this comment.
I thought Charters also follow the RFC process?
There was a problem hiding this comment.
Charters were bootstrapped before the RFC process - https://github.com/HumanCellAtlas/dcp-community/tree/master/charters - so they have their own process.
| roadmap to completion which also weakens the implication of the RFC. | ||
|
|
||
| We propose that, in order to ensure that RFCs are created based on critical tickets that are prioritized based on | ||
| the quarterly and yearly roadmaps and ensure that RFCs are followed up to completion, that all |
There was a problem hiding this comment.
There are no quarterly and yearly roadmaps - there is a multiple quarter or long term product roadmap that is refreshed on a quarterly basis.
There was a problem hiding this comment.
Switched to "long term product roadmap."
rfcs/text/0001-rfc-process.md
Outdated
|
|
||
| There are two types of RFCs that may be proposed: ***informational*** RFCs and ***non informational*** RFCs. | ||
| Non informational RFCs are expected to be linked directly to an existing ticket in the DCP Zenhub board which will | ||
| usually be tagged as a Spike. Informational RFCs are more speculative and need not directly reference an open ticket in |
There was a problem hiding this comment.
Informational RFCs do not need to be speculative but do need to "inform" the community. Sometimes, they simply document something. At the IETF - https://tools.ietf.org/html/rfc8612 is an example of an informational RFC.
I shared some thoughts about informational RFCs in our first example - image based-transcriptomics - in my shepherd writeup which may be helpful especially in thinking about what "approval" means for this RFC type:
Note to Technical Architecture approvers: This is intended to be the first case for an Informational RFC type, in addition to Governance and Architecture RFC(s). The RFC process will be amended to include this type based on demonstrated need.
This RFC has completed a broad community review across impacted components. The authors are only requesting approval to publish background material in our central RFC repository to educate the DCP community about image-based transcriptomics assays and the minimum set of deliverables required for support in the DCP. It is expected that future Technical RFC(s) will be authored for specific technical deliverables.
Informational specifications are common in the Internet Engineering Task Force (IETF) and the Python Enhancement Process (PEP). For example, the IETF describes:
An "Informational" specification is published for the general information of the Internet community, and does not represent an Internet community consensus or recommendation. The Informational designation is intended to provide for the timely publication of a very broad range of responsible informational documents from many sources, subject only to editorial considerations and to verification that there has been adequate coordination with the standards process (see section 4.2.3).
There was a problem hiding this comment.
Thank you for the thorough background on informational RFCs. How about I re-word it to (and I'm stealing much from the IETF definition here):
"Informational RFCs are more of a compilation of results from performing a case study or research on a topic related to the DCP. There need not be consensus on the RFC nor any actionable outcome unlike non-informational RFCs."
rfcs/text/0001-rfc-process.md
Outdated
| usually be tagged as a Spike. Informational RFCs are more speculative and need not directly reference an open ticket in | ||
| the DCP Zenhub board. | ||
|
|
||
| Prior to proposing an ***informational*** RFC, it is recommended that authors engage the DCP community to build |
There was a problem hiding this comment.
I don't see the need in the case of an Informational RFC. You're just sharing information.
There was a problem hiding this comment.
Fair enough. I will delete this section
According to Brian, the DCP Community includes both users + DCP PM + DCP tech. (Correct me if I'm wrong @brianraymor). The decision to drop Oversight was simply based on behavior. Given that the trending behavior today is to start implementing the RFCs during Oversight review, I think we should adjust the process. We can bring it back at a later point if we see the need. |
All changes have been merged into the pr to RFC1
maniarathi
force-pushed
the
rfc-updates
branch
from
a534d99
to
9fc0148
Compare
* Initial RFC outline for proposed changes to the RFC process. * PLEASE DO NOT REVIEW * Update rfcs/text/0000-rfc-process-updates.md Co-Authored-By: Ambrose J Carr <ambrosejcarr@users.noreply.github.com> * Added sections for improving visibility of status and authorship * Formattig to keep problem and solutions close together in the text * Clarify requirements for adding visibility into pre-rfcs * Fixing some grammar, rewording. * Fixing a few typos based on mweiden's feedback. * Changing up wording around pre-rfcs. * Adding note to please not review. * Making changes directly in the RFC process MD file while explicitly stating where additions, updates, and deletions are being made. * Adjusting line breaks for easy diff-ing. * Formatted and addressing comments. * Changing word from roadmap to timeline. * Switched quarterly and yearly roadmaps to long-term product roadmap. * Adding a Deprecating RFC section. * Adding Arathi and Dave as RFC authors. * Updating definition of DCP Community Members. * Removing Timeline section from RFC template. * Cleaning up Timeline related wording in RFC itself. * Reformatting names and emails. * Switching wording from tag to label. * Some more edits on wording. * More rewording. * Removed a sentence that had confusing wording about level of detail required for RFC. * Remove incomplete section. * Rewriting withdrawn section. * Remove the word non-informational. * Reformatting + better delegation of shepherd vs author tasks. * Fixing typos. * Adding key word language. * Fix typos * Delete 0000-rfc-process-updates.md All changes have been merged into the pr to RFC1 * Addressing BrianR's comments. * Usurp last mentions of oversight review. * Updating PR template according to new RFC process.
September 24: Last call for community review(EXTENDED) September 27: Last call for community reviewOctober 4: Last call for oversight review!October 17: Up for approval at DCP PM meeting.October 17: Approved at DCP PM meeting!
Summary of comments from community review: Addressed concerns around adding a Timeline section to the template (which has been removed), elucidating three main types of RFCs, and general editorial comments.