From patchwork Tue Oct 31 11:08:04 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Simon Tournier X-Patchwork-Id: 55726 Return-Path: X-Original-To: patchwork@mira.cbaines.net Delivered-To: patchwork@mira.cbaines.net Received: by mira.cbaines.net (Postfix, from userid 113) id 8C73B27BBEA; Tue, 31 Oct 2023 11:08:38 +0000 (GMT) X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on mira.cbaines.net X-Spam-Level: X-Spam-Status: No, score=-2.7 required=5.0 tests=BAYES_00,DKIM_ADSP_CUSTOM_MED, DKIM_INVALID,DKIM_SIGNED,FREEMAIL_FROM,MAILING_LIST_MULTI, SPF_HELO_PASS,URIBL_BLOCKED autolearn=ham autolearn_force=no version=3.4.6 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mira.cbaines.net (Postfix) with ESMTPS id A8F2827BBE2 for ; Tue, 31 Oct 2023 11:08:36 +0000 (GMT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qxmbl-0002NR-II; Tue, 31 Oct 2023 07:08:29 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qxmbk-0002NG-UM for guix-patches@gnu.org; Tue, 31 Oct 2023 07:08:28 -0400 Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qxmbk-0006WF-MC for guix-patches@gnu.org; Tue, 31 Oct 2023 07:08:28 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1qxmcI-0006Hm-B9 for guix-patches@gnu.org; Tue, 31 Oct 2023 07:09:02 -0400 X-Loop: help-debbugs@gnu.org Subject: [bug#66844] [PATCH] rfc: Add Request-For-Comment process. References: In-Reply-To: Resent-From: Simon Tournier Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Tue, 31 Oct 2023 11:09:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 66844 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: 66844@debbugs.gnu.org Cc: Simon Tournier Received: via spool by 66844-submit@debbugs.gnu.org id=B66844.169875053624149 (code B ref 66844); Tue, 31 Oct 2023 11:09:02 +0000 Received: (at 66844) by debbugs.gnu.org; 31 Oct 2023 11:08:56 +0000 Received: from localhost ([127.0.0.1]:47599 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qxmcB-0006HR-Id for submit@debbugs.gnu.org; Tue, 31 Oct 2023 07:08:56 -0400 Received: from mail-lj1-x22a.google.com ([2a00:1450:4864:20::22a]:37910) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qxmc8-0006H9-U3 for 66844@debbugs.gnu.org; Tue, 31 Oct 2023 07:08:54 -0400 Received: by mail-lj1-x22a.google.com with SMTP id 38308e7fff4ca-2c506d1798eso19396121fa.0 for <66844@debbugs.gnu.org>; Tue, 31 Oct 2023 04:08:19 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1698750493; x=1699355293; darn=debbugs.gnu.org; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to; bh=qZHESJVkpfe/VUvgIaqGnTe10dOzXgfahyITjHIf9Z4=; b=Yj2EgGgCtMmWeuAa3iUAdkh/GC0I0pe2Hz2C/CWHPcKqHW6Yk23rUsrBujsTRIPBT7 6X+4nUXfegyub9JVjiazp/VG9CbxNjkoCPxZeD+q5eoje3L0ZjsCD8cLc0sqyUgKnxgQ 90wgupsW6b5X7EcqNPW8jVaf3ZZEXB1qAfPiUMSQLGL/tbR48uUHBGb1MsJtnkULD+81 baoEWvay3HmZb/2RhVVsHEszhMHVfYH82DCQKt4fs2vhsex6KqHuDfwrQ7PyNPKunEQ/ Xo+TvTJQQFdWbxCrhmpNtGsh38Z+XKBpF2oUogl3IqpnslOFADNej3dxcQiu671F2NG8 AxRQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1698750493; x=1699355293; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=qZHESJVkpfe/VUvgIaqGnTe10dOzXgfahyITjHIf9Z4=; b=eDRAxYEEZeBEdpHzYIIvlz+CoeXRbhs9XvYUmgp79nIz0vnQNFycu5oFfxZ90EC7Ps zVs3OlDjZUBNexUiONub3OoBGFeuNrC4m/i2RivYUHcnwrQh2krVJ06GlgBLF9PfwCNe zSPop5zBdeK+vAimquZE9mC2RWPfB1gxa7TfbvKBY8uhhSdbKi52pfxg2zZJjfqwaod5 PJIK2DMkMseTDOGKoOszEU5ft0lwnKMkeHpYqIFM9Ji7/RWtEdUQ6V6CE7pVmSu2TzNC XFKyhd/Lhk6a3C1PNTzpKZEM0xFvIURIX2vODW+NZan4PCImm0Lzf/XkDlmUJsFT2MMM WWFw== X-Gm-Message-State: AOJu0YxNv7aU0copWrfsdfhZwDgMrl1Ta3zpwWUp3havQz2wmt10j6NV vsTSUPN8CoC437oUIkP88aM0KtigE1Y= X-Google-Smtp-Source: AGHT+IHkz97MCRUWLI5gvtsRDTC54M+qQsKvs+HvO1FSWuqSaYqMxrbJhihS1/kKYkTtvPoCroQD2A== X-Received: by 2002:a2e:a9a2:0:b0:2bf:e5dc:aa68 with SMTP id x34-20020a2ea9a2000000b002bfe5dcaa68mr9582990ljq.3.1698750492701; Tue, 31 Oct 2023 04:08:12 -0700 (PDT) Received: from localhost.localdomain ([193.48.40.241]) by smtp.gmail.com with ESMTPSA id j20-20020a05600c485400b004063cd8105csm1429650wmo.22.2023.10.31.04.08.12 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 31 Oct 2023 04:08:12 -0700 (PDT) From: Simon Tournier Date: Tue, 31 Oct 2023 12:08:04 +0100 Message-ID: X-Mailer: git-send-email 2.41.0 MIME-Version: 1.0 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org Sender: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org X-getmail-retrieved-from-mailbox: Patches * rfc/0001-rfc-process.txt: New file. * rfc/0000-template.txt: New file. Change-Id: Ide88e70dc785ab954ccb42fb043625db12191208 --- rfc/0000-template.txt | 58 +++++++++++++ rfc/0001-rfc-process.txt | 180 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 238 insertions(+) create mode 100644 rfc/0000-template.txt create mode 100644 rfc/0001-rfc-process.txt base-commit: c0895371c5759c7d9edb330774e90f192cc4cf2c diff --git a/rfc/0000-template.txt b/rfc/0000-template.txt new file mode 100644 index 0000000000..22dca35a56 --- /dev/null +++ b/rfc/0000-template.txt @@ -0,0 +1,58 @@ +# -*- mode:org -*- +#+TITLE: +#+DATE: + ++ Issue: ++ Status: ++ Supporter: ++ Co-supporter(s): + +* Summary + +A one-paragraph explanation. Main sales pitch. + +* Motivation + +Describe the use case as clearly as possible and optionally give an example. +Explain how the status quo is insufficient or not ideal. This section answers +Why is this proposal a good idea? Why is it worth the effort to discuss and +implement such? + +* Detail design + +Main part. The sections answers What is the cost of this proposal compared to +status quo or potential alternatives? Explain details, corner cases, provide +examples. Explain it so that someone familiar can understand. + +It is best to exemplify, contrived example too. If the Motivation section +describes something that is hard to do without this proposal, this is a good +place to show how easy that thing is to do with the proposal. + +** Backward Compatibility + +Will your proposed change cause a behaviour change? Assess the expected +impact on existing code on the following scale: + +0. No breakage +1. Breakage only in extremely rare cases (exotic or unknown cases) +2. Breakage in rare cases (user living in cutting-edge) +3. Breakage in common cases + +Explain why the benefits of the change outweigh the costs of breakage. +Describe the migration path. Consider specifying a compatibility warning for +one or more releases. Give examples of error that will be reported for +previously-working cases; do they make it easy for users to understand what +needs to change and why? + +The aim is to explicitely consider beforehand potential Backward Compatibility +issue. + +* Unresolved questions + +Explicitly list any remaining issues. At submitting time, be upfront and +trust that the community will help. At reviewing time, this section tracks +the details about the status of the process. + +At the end of the process, this section will be empty. If not, please be +explicit with the known issues by adding a dedicated subsection under Detail +design. diff --git a/rfc/0001-rfc-process.txt b/rfc/0001-rfc-process.txt new file mode 100644 index 0000000000..8424303949 --- /dev/null +++ b/rfc/0001-rfc-process.txt @@ -0,0 +1,180 @@ +# -*- 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 controlled path for new features to enter the Guix project, so that all +stakeholders can be confident about the direction it is evolving in. + +* Motivation + +The freewheeling way that we add new features to Guix has been good for early +development, but for Guix to become a broadly used system we need to develop +some more self-discipline when it comes to changing our beloved system. 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 substancial 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 agree 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) + + massive Python 2 removal + (Merging the purge-python2-packages branch, mailing list guix-devel) + + 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. + + + Any change that modifies Guix API + + Big restructuring of packages + + Introduction or removal of subcommands + +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 + +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 is 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 +rfcs/unsuccessful/. + +** 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. + +** Comment period + +It is up to the supporter and co-supporter to ensure that sufficient +discussion is solicited. Let two weeks for people to comment is a good +average. Make sure that all have the time for expressing their comments. The +proposal is about significant changes, thus more time is better than less. + +** 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 + +Whoever merges the successful RFC should do the following: + + 1. Fill in the remaining metadata in the RFC header, including links for the + original Debbugs submission. + 2. Commit everything. + +** Template of RFC + +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. + +** 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