From 9cf87fb8a848054258cf7f08075f95d1085343f7 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Tue, 10 Jan 2023 18:36:46 +0100 Subject: [PATCH 1/5] Initial draft --- rfcs/0138-rfc-repos.md | 65 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 rfcs/0138-rfc-repos.md diff --git a/rfcs/0138-rfc-repos.md b/rfcs/0138-rfc-repos.md new file mode 100644 index 000000000..e837e8abf --- /dev/null +++ b/rfcs/0138-rfc-repos.md @@ -0,0 +1,65 @@ +--- +feature: rfc-repos +start-date: 2022-01-10 +author: Silvan Mosberger +co-authors: (find a buddy later to help out with the RFC) +shepherd-team: (names, to be nominated and accepted by RFC steering committee) +shepherd-leader: (name to be appointed by RFC steering committee) +related-issues: (will contain links to implementation PRs) +--- + +# Summary +[summary]: #summary + +Develop and discuss RFCs in repositories instead of a pull request. + +# Motivation +[motivation]: #motivation + +RFC discussions are currently held in single pull requests on the [rfcs](https://github.com/NixOS/rfcs/pulls) repository. +Due to GitHub's limitations on pull requests, this quickly becomes unmanageable. +The most prominent example of this is [the Flakes RFC](https://github.com/NixOS/rfcs/pull/49) with over 500 comments. + +# Detailed design +[design]: #detailed-design + +The RFC process is changed to use repositories to develop and review RFCs instead. +To create a new RFC, an issue on the [rfcs](https://github.com/NixOS/rfcs) repository is opened. +It should contain the following contents describing the process: + +> This RFC is developed as the README.md of this repository: https://github.com/$owner/$repo +> +> To review the RFC +> - Open https://github.com/$owner/$repo/blob/master/README.md?plain=1 +> - Select the lines you wish to comment on +> - Click the "..." menu on the left +> - Select "Reference in new issue" to open a new issue commenting on those lines +> +> To suggest changes, open a PR against the repository. +> +> All issues and pull requests must be resolved before the FCP can be initiated and completed. +> +> This issue may only be used for RFC meta-discussions, such as shepherd nominations, FCP periods, meeting schedules, etc. + +The FCP must be initiated on a specific commit of the repository. +When the FCP passes, the repositories contents are committed to the [rfcs](https://github.com/NixOS/rfcs) repository by the [RFC steering committee](https://github.com/NixOS/rfcs#rfc-steering-committee) via a pull request that closes the original issue. + +# Examples and Interactions +[examples-and-interactions]: #examples-and-interactions + + +# Drawbacks +[drawbacks]: #drawbacks + + +# Alternatives +[alternatives]: #alternatives + + +# Unresolved questions +[unresolved]: #unresolved-questions + + +# Future work +[future]: #future-work + From c0a80fb1969aaa89ab28cf28ae9b8ff25c3cfa95 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Mon, 20 Mar 2023 22:14:58 +0100 Subject: [PATCH 2/5] Updates - From the meeting notes: https://discourse.nixos.org/t/2023-03-06-rfc-138-developing-rfcs-in-repositories-meeting-1/26075 - The steering committee should just make a commit, not an entire PR when it gets accepted - Add shepherd team --- rfcs/0138-rfc-repos.md | 36 ++++++++++++++++++++++++++++++++---- 1 file changed, 32 insertions(+), 4 deletions(-) diff --git a/rfcs/0138-rfc-repos.md b/rfcs/0138-rfc-repos.md index e837e8abf..3dcb94503 100644 --- a/rfcs/0138-rfc-repos.md +++ b/rfcs/0138-rfc-repos.md @@ -3,8 +3,8 @@ feature: rfc-repos start-date: 2022-01-10 author: Silvan Mosberger co-authors: (find a buddy later to help out with the RFC) -shepherd-team: (names, to be nominated and accepted by RFC steering committee) -shepherd-leader: (name to be appointed by RFC steering committee) +shepherd-team: @winterqt, @lheckemann +shepherd-leader: @lheckemann related-issues: (will contain links to implementation PRs) --- @@ -42,7 +42,14 @@ It should contain the following contents describing the process: > This issue may only be used for RFC meta-discussions, such as shepherd nominations, FCP periods, meeting schedules, etc. The FCP must be initiated on a specific commit of the repository. -When the FCP passes, the repositories contents are committed to the [rfcs](https://github.com/NixOS/rfcs) repository by the [RFC steering committee](https://github.com/NixOS/rfcs#rfc-steering-committee) via a pull request that closes the original issue. +When the FCP passes, the repositories contents are committed to the [rfcs](https://github.com/NixOS/rfcs) repository by the [RFC steering committee](https://github.com/NixOS/rfcs#rfc-steering-committee) with a commit that closes the original issue. + +## Workflow to get RFC updates +To get updates for RFC's, instead of subscribing to the PR, one has to watch the repository. + +## Repository transfer + +Once the RFC is merged, the repository has to be transferred to the NixOS organization under https://github.com/NixOS/rfc-NUMBER. This is to ensure the discussions aren't lost in the future. The repository will then be archived. # Examples and Interactions [examples-and-interactions]: #examples-and-interactions @@ -50,11 +57,25 @@ When the FCP passes, the repositories contents are committed to the [rfcs](https # Drawbacks [drawbacks]: #drawbacks - +- There's no line-comment view anymore (the "Files changed" tab for PR's), where you can see the entire proposal and all (up-to-date) line comments. +- Commenting on an RFC won't automatically subscribe you to updates anymore. # Alternatives [alternatives]: #alternatives +## Optional instead of required + +Instead of requiring this process, it could be opt-in for "bigger" RFCs. +- (-) It's not clear how to decide whether an RFC should have a repository, there's no way to know how big discussions become in advance. + +## 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). + - (+) For time-distinct RFCs it can be worked around by [detaching the old fork](https://support.github.com/request/fork) and creating a new one +- (+) Simplifies the RFC process, since one can just create a PR to upstream it + - (-) However this may again lead to the original problem of having too long PR discussions + - (-) It's also confusing about whether a PR is needed # Unresolved questions [unresolved]: #unresolved-questions @@ -63,3 +84,10 @@ When the FCP passes, the repositories contents are committed to the [rfcs](https # Future work [future]: #future-work +- More RFC automation is possible in the future: + - Creating repositories for discussing issues created in the rfcs repository + - Assigning the shepherd team and requiring them to review PRs to the repository + - Announce FCP when all issues/PRs are closed + - Commit contents to rfcs repository once FCP passed without any new issues/PRs + + From e6a921c942bce87d578b14d1c5a21ae0e5ac2cb0 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Mon, 3 Apr 2023 20:43:09 +0200 Subject: [PATCH 3/5] Drawback: Less separation between authors and reviewers --- rfcs/0138-rfc-repos.md | 1 + 1 file changed, 1 insertion(+) diff --git a/rfcs/0138-rfc-repos.md b/rfcs/0138-rfc-repos.md index 3dcb94503..f3d039d5d 100644 --- a/rfcs/0138-rfc-repos.md +++ b/rfcs/0138-rfc-repos.md @@ -59,6 +59,7 @@ Once the RFC is merged, the repository has to be transferred to the NixOS organi [drawbacks]: #drawbacks - There's no line-comment view anymore (the "Files changed" tab for PR's), where you can see the entire proposal and all (up-to-date) line comments. - Commenting on an RFC won't automatically subscribe you to updates anymore. +- Less separation between RFC authors and reviewers with edit suggestions, making it harder to decide who may be a shepherd, since authors can't be shepherds. # Alternatives [alternatives]: #alternatives From 94bad5e0ce1d2a357478638ee8a5dc0680d0c616 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Mon, 8 Jan 2024 17:01:03 +0100 Subject: [PATCH 4/5] Extend motivation --- rfcs/0138-rfc-repos.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/rfcs/0138-rfc-repos.md b/rfcs/0138-rfc-repos.md index f3d039d5d..4c2fa1a02 100644 --- a/rfcs/0138-rfc-repos.md +++ b/rfcs/0138-rfc-repos.md @@ -17,8 +17,13 @@ Develop and discuss RFCs in repositories instead of a pull request. [motivation]: #motivation RFC discussions are currently held in single pull requests on the [rfcs](https://github.com/NixOS/rfcs/pulls) repository. -Due to GitHub's limitations on pull requests, this quickly becomes unmanageable. -The most prominent example of this is [the Flakes RFC](https://github.com/NixOS/rfcs/pull/49) with over 500 comments. +- Due to GitHub's limitations on pull requests, this quickly becomes unmanageable. + The most prominent example of this is [the Flakes RFC](https://github.com/NixOS/rfcs/pull/49) with over 500 comments. +- These PR threads easily get polluted with minor points like typos and wording improvements, + which are not meaningful to the RFCs contents, but distract from other more important discussions. +- It's easiest to comment at the top-level, without threads, + especially when there's no relevant line of the diff to comment on for a thread. + This frequently causes multiple discussions to be interleaved at the top-level. # Detailed design [design]: #detailed-design From 08e64fceda7deb9543856913e5f665c306060b8a Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Mon, 8 Jan 2024 17:01:12 +0100 Subject: [PATCH 5/5] Mention and address drawback of invisible force pushes --- rfcs/0138-rfc-repos.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/rfcs/0138-rfc-repos.md b/rfcs/0138-rfc-repos.md index 4c2fa1a02..231c94945 100644 --- a/rfcs/0138-rfc-repos.md +++ b/rfcs/0138-rfc-repos.md @@ -65,6 +65,13 @@ Once the RFC is merged, the repository has to be transferred to the NixOS organi - There's no line-comment view anymore (the "Files changed" tab for PR's), where you can see the entire proposal and all (up-to-date) line comments. - Commenting on an RFC won't automatically subscribe you to updates anymore. - Less separation between RFC authors and reviewers with edit suggestions, making it harder to decide who may be a shepherd, since authors can't be shepherds. +- Force pushes won't be visible anymore in the history. + - Force pushing shouldn't be necessary for RFCs, since they always get squash merged anyways + - With the previous approach, perhaps the main use case of force pushing was to reduce the PR items to be loaded, + since commits also count towards the number of items loaded by GitHub. + This is obviously not necessary anymore. + - It would be good to protect the main branch for active RFCs, + which could be done by requiring the RFC repo be moved to the NixOS organisation. # Alternatives [alternatives]: #alternatives