From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp0.migadu.com ([2001:41d0:403:4876::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms13.migadu.com with LMTPS id IISbOKnn8Wa8KwEAqHPOHw:P1 (envelope-from ) for ; Mon, 23 Sep 2024 22:11:54 +0000 Received: from aspmx1.migadu.com ([2001:41d0:403:4876::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp0.migadu.com with LMTPS id IISbOKnn8Wa8KwEAqHPOHw (envelope-from ) for ; Tue, 24 Sep 2024 00:11:54 +0200 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=debbugs.gnu.org header.s=debbugs-gnu-org header.b=uZlDsElM; dkim=fail ("headers rsa verify failed") header.d=gnu.org header.s=fencepost-gnu-org header.b=e6K2ttFZ; spf=pass (aspmx1.migadu.com: domain of "guix-patches-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-patches-bounces+larch=yhetil.org@gnu.org"; dmarc=pass (policy=none) header.from=gnu.org ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1727129513; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding:resent-cc: resent-from:resent-sender:resent-message-id:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=0ZDyhNd0qVGkFSpy7SkW95JaBKD5kEo0zJ5NE5qP1Dc=; b=pd43D01P9aDubpzUiVKLV/ql7w7L4flFQYzy/dxhfS9ZNWnzyGKfZaY6klerQaMwgNjbhd IMjB3W5CjieYdHgywc53OQYU46JHeUCmR5CxMLF1WM8eft7Q5uZJIFVOorGBCyxfmrD5Sh jJFHd+mbxPyXz023jTIvRpgMQHskf1AURJs6zS0v3nisHp5MYiI1bJtvPjx8LNVRbYqESD wN4L98kqiDWHeM7FylhW1nWaCrMxxStoZl+37QYLDJgxGkqP6mcJ5VgbiDBt7Ym2VVGw3/ abS9RoDB6ff1v+Qod0VVkCGsSIBUUdSI7A6gm9Qr9oX34fFMYw92bsytW1k0BA== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=debbugs.gnu.org header.s=debbugs-gnu-org header.b=uZlDsElM; dkim=fail ("headers rsa verify failed") header.d=gnu.org header.s=fencepost-gnu-org header.b=e6K2ttFZ; spf=pass (aspmx1.migadu.com: domain of "guix-patches-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-patches-bounces+larch=yhetil.org@gnu.org"; dmarc=pass (policy=none) header.from=gnu.org ARC-Seal: i=1; s=key1; d=yhetil.org; t=1727129513; a=rsa-sha256; cv=none; b=fHXzwWw9JXileNLoX47KNj5tNUDEaLVxBzr6r7hWpL6Sxz6G3bLwtspE1SpSxC36tLR+b7 FRIlDNaQnXzAOYeILKT9UG4bnpzrYQjZoW2xkDfLlRY2UV5fWZuUZO/u+v4F+/7PCT4t5G bhLLhmPcL1PMZsiwEoqu0SYpxI4k5Rt+X/WJHoFNSoW4um1+bfpcAuiINFGxq4fX151ymJ PaTmV/d1jizI2KtZAU15QrEYVE6wrU1/wz9h+WtMEPw02AL9Al5yE3YWQAzKp2K9c9ulV9 x991iJWXMR+CGjeX6f+0HzUnagaX3O2rEuV9vLrN0As30BHYO3ypuzCU1gzDhw== Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 73B7D75482 for ; Tue, 24 Sep 2024 00:11:53 +0200 (CEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ssrHR-0000sp-Ov; Mon, 23 Sep 2024 18:11:41 -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 1ssrHQ-0000sJ-8C for guix-patches@gnu.org; Mon, 23 Sep 2024 18:11:40 -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 1ssrHP-0001RD-KY; Mon, 23 Sep 2024 18:11:39 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=debbugs.gnu.org; s=debbugs-gnu-org; h=MIME-Version:References:In-Reply-To:Date:From:To:Subject; bh=0ZDyhNd0qVGkFSpy7SkW95JaBKD5kEo0zJ5NE5qP1Dc=; b=uZlDsElMHHm12id83qKWbYhrGoARN0xfUaGiDT5BfwG9SMY36q5bthTlS1Yqe2C+e92D55bE+JAXPwOI1D3UhlBg/Gn0ZcV0YJKlDQqoU0tX50NH6XAJogd4FRPb6YHzStAMzfsDG2SaFNUNcFkvO6/f2oqk8Mik3KjF/LneRqIYsa22XtaeFmOuwVJEWB/6NPnL+EVqkhhSh7BsP7cwODOUtNMReY29mHeF4+XsmasFSuUrvPfpBAZTjVZYnvsMOIVl7kTVh9DhNUplhCukdZelH6jRUMtz4UCosFatl/Uvp7jSMe+doRAQw1LnUc+Y+JH4GWf6YW/plnt60qHAJQ==; Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1ssrHm-0001P8-Ix; Mon, 23 Sep 2024 18:12:02 -0400 X-Loop: help-debbugs@gnu.org Subject: [bug#72840] [PATCH RFC v4] doc: Add =?UTF-8?Q?=E2=80=9CDeprecation_?= =?UTF-8?Q?Policy=E2=80=9D?= section. Resent-From: Ludovic =?UTF-8?Q?Court=C3=A8s?= Original-Sender: "Debbugs-submit" Resent-CC: pelzflorian@pelzflorian.de, ludo@gnu.org, maxim.cournoyer@gmail.com, guix-patches@gnu.org Resent-Date: Mon, 23 Sep 2024 22:12:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 72840 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: To: 72840@debbugs.gnu.org Cc: =?UTF-8?Q?No=C3=A9?= Lopez , Ludovic =?UTF-8?Q?Court=C3=A8s?= , Konrad Hinsen , andreas@enge.fr, Florian Pelz , Ludovic =?UTF-8?Q?Court=C3=A8s?= , Maxim Cournoyer X-Debbugs-Original-Xcc: Florian Pelz , Ludovic =?UTF-8?Q?Court=C3=A8s?= , Maxim Cournoyer Received: via spool by 72840-submit@debbugs.gnu.org id=B72840.17271295215383 (code B ref 72840); Mon, 23 Sep 2024 22:12:02 +0000 Received: (at 72840) by debbugs.gnu.org; 23 Sep 2024 22:12:01 +0000 Received: from localhost ([127.0.0.1]:44836 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ssrHk-0001Ok-6Z for submit@debbugs.gnu.org; Mon, 23 Sep 2024 18:12:00 -0400 Received: from eggs.gnu.org ([209.51.188.92]:45778) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ssrHh-0001OQ-L8 for 72840@debbugs.gnu.org; Mon, 23 Sep 2024 18:11:58 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ssrHD-0001QO-Pt; Mon, 23 Sep 2024 18:11:27 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-Version:References:In-Reply-To:Date:Subject:To: From; bh=0ZDyhNd0qVGkFSpy7SkW95JaBKD5kEo0zJ5NE5qP1Dc=; b=e6K2ttFZeI8Ck8C7jx48 gT22wGmSfNXFderzefrIFVeV7AKUEJm7wPzAP0BGwmvwUdIhj3A0h5QmsgEmpVAczj1pphwyf1BJL BKp7M5JV1EKRrBRo/Td98k67FdntiHtUXcYvEBFF2mk6QIrkikm/O7TjUotHmCp0QYunCQ0xH6J8V L9scKQOS85diH232hKQKhyV/VTG/EHD1fPMl48WiPOgkClA76nY4OKWmIBAmRQefAg20rSqz3s91I E5QpBQRtsxo++iIwHTwBjQAEFu8svEQRH+XQn5bYo18l94KlhuN71lcL63XXOofy5eBnJkigt7QDT Kddjolt5KpWAuQ==; From: Ludovic =?UTF-8?Q?Court=C3=A8s?= Date: Tue, 24 Sep 2024 00:11:19 +0200 Message-ID: <7b092101ad70b100c147b7dacb6efc3393f6cb06.1727129087.git.ludo@gnu.org> X-Mailer: git-send-email 2.46.0 In-Reply-To: <902c544b5298617c2ed45af8d672130bc9b1a2e3.1726049102.git.ludo@gnu.org> References: <902c544b5298617c2ed45af8d672130bc9b1a2e3.1726049102.git.ludo@gnu.org> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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+larch=yhetil.org@gnu.org Sender: guix-patches-bounces+larch=yhetil.org@gnu.org X-Migadu-Flow: FLOW_IN X-Migadu-Country: US X-Migadu-Spam-Score: -4.51 X-Spam-Score: -4.51 X-Migadu-Queue-Id: 73B7D75482 X-Migadu-Scanner: mx10.migadu.com X-TUID: sAWsKeSZtQSD * doc/contributing.texi (Deprecation Policy): New node. (Commit Access): Link to ‘package-removal-policy’. Change-Id: I5d095559920a3d9b791b5d919aab4e2f2a0c2dee --- doc/contributing.texi | 199 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 196 insertions(+), 3 deletions(-) Changes since v3: • Mention “development *or use* of external tools” (Konrad) in the list of use cases. • Mark upgrade as potentially equivalent to removal (Noé, Konrad). • Mark packages “failing to build for two months or more” as candidates for removal (Andreas). That makes it a total of at least 3 months before removal. The last point is probably the most contentious. Anything else? Ludo’. diff --git a/doc/contributing.texi b/doc/contributing.texi index 73f7addbef..d6a684306c 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -34,6 +34,7 @@ Contributing * Commit Access:: Pushing to the official repository. * Reviewing the Work of Others:: Some guidelines for sharing reviews. * Updating the Guix Package:: Updating the Guix package definition. +* Deprecation Policy:: Commitments and tools for deprecation. * Writing Documentation:: Improving documentation in GNU Guix. * Translating Guix:: Make Guix speak your native language. @end menu @@ -2805,9 +2806,11 @@ Commit Access repository, especially for the @code{master} branch. If you're committing and pushing your own changes, try and wait at least -one week (two weeks for more significant changes) after you send them -for review. After this, if no one else is available to review them and -if you're confident about the changes, it's OK to commit. +one week (two weeks for more significant changes, up to one month for +changes such as removing a package---@pxref{package-removal-policy, +Package Removal}) after you send them for review. After this, if no one +else is available to review them and if you're confident about the +changes, it's OK to commit. When pushing a commit on behalf of somebody else, please add a @code{Signed-off-by} line at the end of the commit log message---e.g., @@ -3030,6 +3033,196 @@ Updating the Guix Package this variable is set, the updated package source is also added to the store. This is used as part of the release process of Guix. +@node Deprecation Policy +@section Deprecation Policy + +@cindex deprecation policy +As any lively project with a broad scope, Guix changes all the time and +at all levels. Because it's user-extensible and programmable, +incompatible changes can directly impact users and make their life +harder. It is thus important to reduce user-visible incompatible +changes to a minimum and, when such changes are deemed necessary, to +clearly communicate them through a @dfn{deprecation period} so everyone +can adapt with minimum hassle. This section defines the project's +commitments for smooth deprecation and describes procedures and +mechanisms to honor them. + +There are several ways to use Guix; how to handle deprecation will +depend on each use case. Those can be roughly categorized like this: + +@itemize +@item +package management exclusively through the command line; + +@item +advanced package management using the manifest and package interfaces; + +@item +Home and System management, using the @code{operating-system} and/or +@code{home-environment} interfaces together with the service interfaces; + +@item +development or use of external tools that use programming interfaces +such as the @code{(guix ...)} modules. +@end itemize + +These use cases form a spectrum with varying degrees of coupling---from +``distant'' to tightly coupled. Based on this insight, we define the +following @dfn{deprecation policies} that we consider suitable for each +of these levels. + +@table @asis +@item Command-line tools +Guix sub-commands should be thought of as remaining available +``forever''. Once a Guix sub-command is to be removed, it should be +deprecated first, and then remain available for @b{at least one year} +after the first release that deprecated it. + +Deprecation should first be announced in the manual and as an entry in +@file{etc/news.scm}; additional communication such as a blog post +explaining the rationale is welcome. Months before the scheduled +removal date, the command should print a warning explaining how to +migrate. An example of this is the replacement of @command{guix +environment} by @command{guix shell}, started in October +2021@footnote{For more details on the @command{guix shell} transition, +see +@uref{https://guix.gnu.org/en/blog/2021/from-guix-environment-to-guix-shell/}.}. + +Because of the broad impact of such a change, we recommend conducting a +user survey before enacting a plan. + +@cindex package deprecation +@item Package name changes +When a package name changes, it must remain available under its old name +for @b{at least one year}. For example, @code{go-ipfs} was renamed to +@code{kubo} following a decision made upstream; to communicate the name +change to users, the package module provided this definition: + +@findex deprecated-package +@lisp +(define-public go-ipfs + (deprecated-package "go-ipfs" kubo)) +@end lisp + +That way, someone running @command{guix install go-ipfs} or similar sees +a deprecation warning mentioning the new name. + +@cindex package removal policy +@anchor{package-removal-policy} +@item Package removal +Packages whose upstream developers have declared as having reached ``end +of life'' or being unmaintained may be removed; likewise, packages that +have been @b{failing to build for two months or more} may be removed. + +There is no formal deprecation mechanism for this case, unless a +replacement exists, in which case the @code{deprecated-package} +procedure mentioned above can be used. + +If the package being removed is a ``leaf'' (no other packages depend on +it), it may be removed after a @b{one-month review period} of the patch +removing it (this applies even when the removal has additional +motivations such as security problems affecting the package). + +If it has many dependent packages---as is the case for example with +Python version@tie{}2---the relevant team must propose a deprecation +removal agenda and seek consensus with other packagers for @b{at least +one month}. It may also invite feedback from the broader user +community, for example through a survey. Removal of all impacted +packages may be gradual, spanning multiple months, to accommodate all +use cases. + +When the package being removed is considered popular, whether or not it +is a leaf, its deprecation must be announced as an entry in +@code{etc/news.scm}. + +@item Package upgrade +In the case of packages with many dependents and/or many users, an +upgrade may be treated like the @emph{removal} of the previous version. + +Examples include major version upgrades of programming language +implementations, as we've seen above with Python, and major upgrades of +``big'' libraries such as Qt or GTK. + +@cindex service deprecation +@item Services +Changes to services for Guix Home and Guix System have a direct impact +on user configuration. For a user, adjusting to interface changes is +rarely rewarding, which is why any such change must be clearly +communicated in advance through deprecation warnings and documentation. + +Renaming of variables related to service, home, or system configuration +must be communicated for at least six months before removal using the +@code{(guix deprecation)} mechanisms. For example, renaming of +@code{murmur-configuration} to @code{mumble-server-configuration} was +communicated through a series of definitions like this one: + +@findex define-deprecated/public-alias +@lisp +(define-deprecated/public-alias + murmur-configuration + mumble-server-configuration) +@end lisp + +Procedures slated for removal may be defined like this: + +@findex define-deprecated +@lisp +(define-deprecated (elogind-service #:key (config (elogind-configuration))) + elogind-service-type + (service elogind-service-type config)) +@end lisp + +Record fields, notably fields of service configuration records, must +follow a similar deprecation period. This is usually achieved through +@i{ad hoc} means though. For example, the @code{hosts-file} field of +@code{operating-system} was deprecated by adding a @code{sanitized} +property that would emit a warning: + +@lisp +(define-record-type* + ;; @dots{} + (hosts-file %operating-system-hosts-file ;deprecated + (default #f) + (sanitize warn-hosts-file-field-deprecation))) + +(define-deprecated (operating-system-hosts-file os) + hosts-service-type + (%operating-system-hosts-file os)) +@end lisp + +When deprecating interfaces in @code{operating-system}, +@code{home-environment}, @code{(gnu services)}, or any popular service, +the deprecation must come with an entry in @code{etc/news.scm}. + +@cindex deprecation of programming interfaces +@item Core interfaces +Core programming interfaces, in particular the @code{(guix ...)} +modules, may be relied on by a variety of external tools and channels. +Any incompatible change must be formally deprecated with +@code{define-deprecated}, as shown above, for @b{at least one year} +before removal. The manual must clearly document the new interface and, +except in obvious cases, explain how to migrate from the old one. + +As an example, the @code{build-expression->derivation} procedure was +superseded by @code{gexp->derivation} and remained available as a +deprecated symbol: + +@lisp +(define-deprecated (build-expression->derivation store name exp + #:key @dots{}) + gexp->derivation + @dots{}) +@end lisp + +Sometimes bindings are moved from one module to another. In those +cases, bindings must be reexported from the original module for at least +one year. +@end table + +This section does not cover all possible situations but hopefully allows +users to know what to expect and developers to stick to its spirit. +Please email @email{guix-devel@@gnu.org} for any questions. + @cindex documentation @node Writing Documentation @section Writing Documentation base-commit: 637ca78f513fac15284403c0d3af64492ea832a1 -- 2.46.0