# -*- mode:org -*- #+TITLE: Request-For-Comment process #+DATE: 2023-10-31 + Issue: 66844 + Status: pending + Supporter: Simon Tournier + Co-supporters: * Summary The "RFC" (request for comments) process is intended to provide a consistent and structured path for major changes and features to enter the Guix project, so that all stakeholders can make decisions collectively and be confident about the direction it is evolving in. * Motivation The current way that we add new features to Guix has been good for early development, but it is starting to show its limits as Guix becomes a broadly used system with many contributors. Changes might be slowed down by the lack of structure to acquire consensus. This is a proposal for a more principled RFC process to make it a more integral part of the overall development process, and one that is followed consistently to introduce substantial features. There are a number of changes that are significant enough that they could benefit from wider community consensus before being introduced. Either because they introduce new concepts, big changes or are controversial enough that not everybody will consent on the direction to take. Therefore, the purpose of this RFC is to introduce a process that allows to bring the discussion upfront and strengthen decisions. This RFC is used to bootstrap the process and further RFCs can be used to refine the process. Note that this process does not cover most of the changes. It covers significant changes, for some examples: + change of inputs style (Removing input labels from package definitions, #49169) + introduction of =guix shell= and deprecation of =guix environment= (Add 'guix shell' to subsume 'guix environment', #50960) + introduction of authentication mechanism (Trustable "guix pull", #22883) + changes in policy (Add "Deprecation Policy", #72840) + collaboration via team and branch-features (several places mailing list guix-devel) * Detail design ** When you need to follow this process This process is followed when one intends to make "substantial" changes to the Guix project. What constitutes a "substantial" change is evolving based on community norms, but may include the following. + Changes that modify user-facing interfaces that may be relied on + Command-line interfaces + Core Scheme interfaces + Big restructuring of packages + Hard to revert changes + Governance and changes to the way we collaborate Certain changes do not require an RFC: - Adding, updating packages, removing outdated packages - Fixing security updates and bugs that don't break interfaces A patch submission to Debbugs that contains any of the afore-mentioned substantial changes may be asked to first submit a RFC. ** How the process works 1. Clone https://git.savannah.gnu.org/git/guix.git 2. Copy rfc/0000-template.org to rfc/00XY-good-name.org where good-name is descriptive but not too long and XY increments 3. Fill RFC 4. Submit to guix-patches@gnu.org 5. Announce your RFC to guix-devel@gnu.org Make sure the proposal is as well-written as you would expect the final version of it to be. It does not mean that all the subtilities must be considered at this point since that is the aim of review discussion. It means that the RFC process is not a prospective brainstorming and the proposal formalize an idea for making it happen. The submission of a proposal does not require an implementation. However, to improve the chance of a successful RFC, it might be recommended to have an idea for implementing it. If an implementation is attached to the detailed design, it might help the discussion. At this point, at least one other person must volunteer to be "co-supporter". The aim is to improve the chances that the RFC is both desired and likely to be implemented. Once supporter and co-supporter(s) are committed in the RFC process, the review discussion starts. Advertisement of the RFC on the mailing-lists guix-devel is mandatory and IRC and other Guix communities are recommended. After a number of rounds of review, the discussion should settle and a general consensus should emerge. If the RFC is successful then authors may contribute to the implementation. This bit is left intentionally vague and should be refined in the future. A successful RFC is not a rubber stamp, and in particular still does not mean the feature will ultimately be merged; it does mean that in principle all the major stakeholders have agreed to the feature and are amenable to merging it. An unsuccessful RFC is *not* a judgment on the value of the work, so a refusal should rather be interpreted as “let’s discuss again with a different angle”. The last state of an unsuccessful RFC is archived under the directory rfc/withdrawn/. ** Co-supporter A co-supporter is a contributor sufficiently familiar with the project’s practices, hence it is recommended, but not mandatory, to be a contributor with commit access. The co-supporter helps the supporter, they are both charged with keeping the proposal moving through the process. The co-supporter role is to help the proposal supporter by being the timekeeper and helps in pushing forward until process completion. The co-supporter doesn't necessarily have to agree with all the points of the RFC but should generally be satisfied that the proposed additions are a good thing for the community. The Guix projects ensures that a team of co-supporters – the RFC team – remain available for any new RFCs that don’t find any co-supporters. This team should be added to the etc/teams.scm file. ** Timeline The lifetime of an RFC is structured into the following periods: submission (7d) ⟶ comments (30–60d) ⟶ last call (14d) ⟶ withdrawn OR final *** Submission The author submits their proposal to the patches mailing list and the RFC team which will read the proposal and can advise the author on improving their RFC. This first round of review is provided only to help the author and should not reflect personal bias or opinions. If seven days have passed without answer or the author thinks that his RFC is ready then he may move on to the comment period. *** Comment The author publishes their RFC to guix-devel and starts a discussion period of at least 30 days. It is up to the supporter and co-supporter to ensure that sufficient discussion is solicited. Make sure that all have the time for expressing their comments. The proposal is about significant changes, thus more time is better than less. The author is encouraged to publish updated versions of their RFC at any point during the discussion period. Once the discussion goes stale or after 60 days, the author should publish or keep their final version and move into the last call period. *** Last call The author publishes a final version of the RFC and a 14 day period is given for people to express their agreement or disagreement. If a positive consensus is reached the RFC becomes final and the changes should be applied in less than six months. If no consensus can be reached or the changes were not applied in less than six months, the RFC becomes withdrawn and is archived. The author may also withdraw their RFC at any point. ** Decision making: consensus It is expected from all contributors, and even more so from committers, to help build consensus and make decisions based on consensus. By using consensus, we are committed to finding solutions that everyone can live with. It implies that no decision is made against significant concerns and these concerns are actively resolved with proposals that work for everyone. A contributor, without or with commit access, wishing to block a proposal bears a special responsibility for finding alternatives, proposing ideas/code or explaining the rationale for the status quo. To learn what consensus decision making means and understand its finer details, you are encouraged to read . ** Merging the outcome Once a consesus is made, a committer should do the following to merge the RFC: 1. Fill in the remaining metadata in the RFC header, including links for the original Debbugs submission. 2. Commit everything. 3. Announce the establishment of the RFC to all the stakeholders. 4. Ensure the RFC is applied within six months. ** Template of RFC # Ludovic Courtès: # I’d go for one format, preferably Markdown because we have a library to # parse it. The structure of the RFC is captured by the template; see the file rfc/0000-template.txt. It is recommended to write using markup language as, for example, Org-mode or Markdown or reStructuredText. ** Backward Compatibility None. ** Forward compatibility The RFC process can be refined by further RFCs. ** Drawbacks There is a risk that the additional process will hinder contribution more than it would help. We should stay alert that the process is only a way to help contribution, not an end in itself. Of course, group decision-making processes are difficult to manage. The ease of commenting may bring a slightly diminished signal-to-noise ratio in collected feedback, particularly on easily bike-shedded topics. ** Open questions There are still questions regarding the desired scope of the process. While we want to ensure that changes which affect the users are well-considered, we certainly don't want the process to become unduly burdensome. This is a careful balance which will require care to maintain moving forward. * Unresolved questions