[RFC 0138] Developing RFCs in repositories #138
Conversation
|
The Nixpkgs Architecture Team is currently developing an RFC in a repository, and it's working really well. I'd think this could be good practice for all RFCs. |
| [drawbacks]: #drawbacks | ||
|
|
||
|
|
||
| # Alternatives |
There was a problem hiding this comment.
I suggest putting more focus on Pre-RFCs and on discussion in the forum. Rust does this and it works really well IMO. A lot of the discussion noise in GitHub threads currently comes to RFCs being posted as drafts containing typos (I've also occasionally witnessed this on Matrix RFCs too), or more generally from the first impact of an idea in the author's head with the reality of a community's opinions. A lot of that can be absorbed by iterating outside of the formal RFC process. I think then the discussion workload on GitHub would remain manageable.
Even when keeping the approach of using GitHub repositories as suggested here, I'd still recommend putting more emphasis on pre-RFC discussions.
There was a problem hiding this comment.
Yeah that's a good suggestion. I think these two ideas go hand-in-hand: You can create a repository for development of the RFC beforehand, and if you want it to become more official, be looked at by more people, etc. open an issue in the rfcs repository linking to the repository where it's being developed.
There was a problem hiding this comment.
Maybe then a ful alternative could look like that:
- in the RFC process: add a field «acknowledgements» to be used mainly for reviewers of early drafts who were only giving feedback and local suggestions and not co-writing the text; clarify these people are eligible to be shepherds
- in the RFC process: establish that representing different viewpoints based on different use patterns in a shepherd team is desired, but only if different viewpoints are actually expressed during the early formal review
- informally: encourage early direction-discussion on Discourse
- informally: encourage splitting the concerns for making progress step by step
- informally: if the minimal useful version is still rather large, encourage a round of drafting in a separate repository before submission, adding the active participants into early reviewers (well, possibly some will also become authors)
I do think that splitting small enough not to need a separate repo is good when possible, and I think that submitting for the final review via the old process after drafting in a repo might be still reasonable otherwise.
|
I think that development of an RFC is not the same as RFC discussion so it is not a precedent. Maybe one way to compare is that a wide RFC discussion is less naturally sequentialisable. If this process is proposed for a wide discussion, what replaces line-comment view? Some more staged workflow might help indeed… |
|
@7c6f434c I do think development and discussion go hand-in-hand, development often happens in PRs and discussions in issues (but also PRs). While you can also do that for individual PR's themselves (development with GitHub suggestions, discussions with comments), it's very sequential, which I don't think works well for RFCs. You're right that there's no replacement for line-comment view, but personally I don't think it even was very valuable. You always really need to look at all the comments to get a sense of the RFC. With this proposal here the replacement for that is the issue/PR tracker of the repository, where you can perform searches, filtering, assigning, etc. |
|
I don't say that discussion without development is a good idea, I am just saying that development by a focused group without wide discussion is not similar enough to wide discussion with development to count as a full precedent. Maybe if you want to run the experiment to completion, we should ask the RFC SC to allow the following procedure: the discussion of this specific submission gets locked immediately with a link to the repository to direct discussion there. I guess when it is RFC time, the PR can be updated, unlocked, and announced on Discourse. Hopefully after the discussion in the repo there will be nothing left to discuss, and FCP can happen quickly… and if not, we might get some information on why not!
There is a stage where it is an absolutely crucial part of the workflow I sometimes use. On the first clean reading I have some paragraph-by paragraph «local» questions. I want to see quickly if there is already a discussion in that place in a similar direction or not. (Note that if there is a similar-ish discussion elsewhere it is not enough, if the current paragraph doesn't intra-document-refer to that elsewhere). Filtering on GitHub is not that powerful (in comparison to tracker-first systems like carefully-configured Redmine), but independently of this the question of code-review-view of the entire thing at once probably needs more magic than I have ever seen deployed in trackers… Another consideration to at least mention somewhere: this radically changes the GitHub notifications experience for reviewing multiple RFCs. |
|
@7c6f434c I appreciate you highlighting a valid use case for line-comment view, we can add this to the RFC. Yes this might take more time with this proposal (searching through the issue list). I don't think it counteracts the benefits of this proposal though. Workflows will change and tradeoffs are involved, the main question should be whether this improves the situation or not. This proposal solves the main problem with RFCs people have been complaining about for years now, which is a pretty strong argument. |
|
I am somewhat afraid whether 500 comments split into 50 issues will just be a different kind of mess to keep track of. (To be fair, GitHub equally doesn't make checking what's new on a single PR discussion simple, so it's two bad options, which is why I wonder how we can have and end-to-end opt-in experiment on a few RFCs before committing to a specific change in mitigations) |
|
In ghc-proposals/ghc-proposals#442 I proposed something somewhat similar for GHC proposals where we'd have a fork of the manual based on what we'd like to do. That's not quite as good a fit here before we multiple projects each with their own manual under discussion, but I bring it up because some of the motivation overlaps. |
lheckemann
added
the
status: open for nominations
|
This RFC is now open for nominations! Feel free to suggest anyone you think would be interested in this RFC, including yourself! |
|
I'd like to nominate myself, as someone who's already involved in the pre-RFC that inspired this. |
|
Isn't this too Github-specific? I believe the idea is worthy, but the verbiage is too coupled to Github interfaces and facilities. I believe it should be made less dependent on Github, because it could be easily adapted to other possible environments - from mailing lists to other forges. |
|
@AndersonTorres For the sake of keeping the controversial changes to a minimum I'd like to limit it to GitHub for now. This way people won't have to learn new interfaces for potentially every PR. It could also allow some common RFC flow automation in the future (e.g. open an issue to create an RFC, automatically creates a repository in the NixOS org, shepherd team has to approve all PRs, automatic FCP if all issues are closed) |
|
I'll self-nominate as someone who's written an RFC that would benefit from this, and also just as someone who wants to help improve the RFC process. |
|
I also think somebody from the @NixOS/rfc-steering-committee should be a shepherd member, because it changes the RFC process itself, and they are de-facto "code owners". |
|
Good idea. I nominate myself then. |
|
That brings us to 3 accepted nominations, so our shepherd team is @winterqt, @roberth and myself :) the Steering Committee has decided on me as a leader. I've opened a Matrix room: https://matrix.to/#/#nix-rfc-0138-team:schreibt.jetzt |
edolstra
added
status: in discussion
and removed
status: open for nominations
|
I regret to have made the wrong estimation before, but I am not able to participate in this RFC. My sincere apologies to the lovely team I was supposed to be part of. I hope someone else can take position soon and give this RFC the attention it deserves. I think it'd be a fun one. |
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/2023-03-06-rfc-138-developing-rfcs-in-repositories-meeting-1/26075/1 |
|
|
||
|
|
||
| # Drawbacks | ||
| [drawbacks]: #drawbacks |
There was a problem hiding this comment.
- the convenient, already existing URL scheme to find any RFC, eg.
https://github.com/nixos/RFCs/pull/138,
(s/138/RFC num), breaks. - Users that give one review don't automatically become watchers on the whole repo
There was a problem hiding this comment.
- the convenient, already existing URL scheme to find any RFC, eg.
https://github.com/nixos/RFCs/pull/138,
(s/138/RFC num), breaks.
This actually still works, because GitHub redirects ../pull/138 to ../issues/138 if it's not a pull request but an issue (which would be the case in the proposal here).
I added the other point to the Drawbacks.
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/2023-03-13-nixpkgs-architecture-team-meeting-32/26287/1 |
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/2023-09-18-nix-team-meeting-minutes-87/33194/6 |
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/decision-making-2-0-1-0-1/12851/27 |
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/decision-making-2-0-1-0-1/12851/28 |
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/pre-rfc-a-single-canonical-domain-name/35102/1 |
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/accessibility-and-obstacles-to-community-contribution/32845/56 |
|
I would like to nominate myself as a shepherd team member for this RFC. @infinisil, please re-open the issue as you see fit :) |
|
|
||
|
|
||
| # Drawbacks | ||
| [drawbacks]: #drawbacks |
There was a problem hiding this comment.
I noticed 2 unmentioned drawbacks (one of which I still don't remember), mentioning one of them here.
- Force pushes to edit something will not be noticed if done directly on the default branch.
- I'll edit it in once I remember, sorry!
As for 1, I have a potential solution in mind; we can transfer the RFC repository to the NixOS org as a WIP RFC and protect the default branch so that all changes are visible in PRs as usual. Also, I really loved the idea of pre-RFCs, I think pre-RFCs could integrate well with this where the transfer would only occur once the pre-RFC has matured into a "normal" one.
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/lets-improve-the-rfc-process/37975/1 |
|
|
||
|
|
||
| # Drawbacks | ||
| [drawbacks]: #drawbacks |
There was a problem hiding this comment.
The 2nd drawback I couldn't remember in my previous thread:
If an RFC has a relatively large amount of traffic, multiple discussions can start on the same logical unit discussing more or less the same thing (or even the exact same thing). While this can be considered relatively trivial to manage, it's still an overhead that I thought needs to be mentioned (which apparently already was here: #138 (comment).
This is a consequence of the previously mentioned absence of the line-comment view.
Solution?
A potential way of solving this can be to have a great label architecture (much like nixpkgs). We could have "broad" labels which could be: drawbacks, alternatives, future-work; pretty self-explanatory but these would essentially mimic all the major headings in the RFC template. Unsure if a general rule can be applied to smaller labels, if not, they will just be a mess.
| # Future work | ||
| [future]: #future-work | ||
|
|
||
| - More RFC automation is possible in the future: |
There was a problem hiding this comment.
In the spirit of automation, I think there will be a strong need of a template repository for RFCs, especially if a label architecture would be enforced as I mentioned in this comment.
| ## Fork branch instead of separate repository | ||
|
|
||
| Instead of creating a new repository for each RFC, a new branch in a fork can be created instead. | ||
| - (-) Means that a single GitHub user/organization can't have more than one RFC open at a time without mixing of issues/PRs occurring (since GitHub only supports having a single fork of a repository). |
There was a problem hiding this comment.
Is this a big issue? Have there been instances in the past where the same person is authoring multiple RFCs simultaneously? And if so, would labels on both issues & PRs by RFC number not solve this problem satisfactorily?
There was a problem hiding this comment.
Unclear. Yes, e.g. 45/46. Maybe.
To be fair, line comments get auto-obsoleted on updates but issues are not; so if a full rewrite test-wise (which 46 has seen) would need probably need labelling even within a single RFC.
There was a problem hiding this comment.
I'm kind of already using this approach and I already have 4 RFC repos :)
- This one
- [RFC 0166] Nix formatting, take two #166 (https://github.com/nix-rfc-101/rfcs) as co-author
- https://github.com/nix-rfc-canonical-domain/rfcs (pre-RFC)
- https://github.com/tweag/epcb (pre-RFC)
I think it would be much cleaner to separate all RFCs with a repository. There's various benefits, like being able to infer that an RFC is likely ready for FCP once issues and PRs are at 0. Or not having to worry about having the correct label. Or the workflow not changing when somebody opens another RFC (before you wouldn't have needed a filter, but now you do), etc.
There was a problem hiding this comment.
Yeah, that makes sense. Might not be worth exploring this alternative, in that case.
infinisil
added
status: open for nominations
|
This RFC has not acquired enough shepherds. This typically shows lack of interest from the community. In order to progress a full shepherd team is required. Consider trying to raise interest by posting in Discourse, talking in Matrix or reaching out to people that you know. If not enough shepherds can be found in the next month we will close this RFC until we can find enough interested participants. The PR can be reopened at any time if more shepherd nominations are made. |
|
I nominate myself following the steering committee meeting. |
|
Not enough interest after all, but there's another effort I'm involved with to improve Nix organisation in general: https://github.com/nix-open-org |
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/rfcsc-meeting-2024-03-05/40851/1 |
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/management-protocol-for-nixos-desktop/42797/25 |
Develop and discuss RFCs in repositories instead of a pull request.
Rendered