From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp0.migadu.com ([2001:41d0:403:58f0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms13.migadu.com with LMTPS id QASiBZgj2mavzAAAqHPOHw:P1 (envelope-from ) for ; Thu, 05 Sep 2024 21:33:12 +0000 Received: from aspmx1.migadu.com ([2001:41d0:403:58f0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp0.migadu.com with LMTPS id QASiBZgj2mavzAAAqHPOHw (envelope-from ) for ; Thu, 05 Sep 2024 23:33:12 +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="Qy/aN1Ru"; dkim=fail ("headers rsa verify failed") header.d=gnu.org header.s=fencepost-gnu-org header.b=WeQKn94b; dmarc=pass (policy=none) header.from=gnu.org; 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" ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1725571991; 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=42LADpVb+ft8sCV1Q5a28K5KnD6jDcEyqilim5vg3Vo=; b=XBapd5wVPtA9r6iaT65HX+r6/nVY2l107tXB0TCFRZMQjBRfS31nnA7UFLsQehKJH040FF OE50GLMQiso0z5a7+2ZdACb3W8RwQcy+V7JA8e5M79o8tbBZj1QPNi8bKKskmtf/TvuMxU VjfXJrpqD2wG9Od81ZAgZKBQ4i11O46G7D3LqpR5GpfGdrh6Xjl7jU0cC4e6G4SuQyIKBr ZBxXpW7B857vV2CsbpHIgdcuH8EPJ4eiy9MT+QqoVFCrIkaMdHee7ns2iL4BhKt1KVnfot py8V+Dj88J536WVZmjXj3aok4yNWSv0KFn/tCimRkccTCZaYRX404NjyoAmLeg== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1725571991; a=rsa-sha256; cv=none; b=NjgVTpBUZqqK/nK3RVKRwGQzZET0ZFTdUK40cn5tDgwNYV3hGXMzi/EED0Tino8NmnNdw8 fSL6spCTVurrygTnbi+IDI2T1YJ+SlMP36zXjzxQRJEYa5nenoa4SbGTH2qUJm65ou6/bY P1bolyY9yJRfCXWzpFvWzq/qNt9cDfoJRNDSCv2DNp/V+XrWRGcK2LCarRlunwayGMzNtI 0gbZwBBZAsN9o4jPDPW/LDY+etJZ6uxMXZf7bK8cIhUEjyjsW7NIcTFS9D5vNjNmG7kDw9 k/YR29TEou91hck2O9n4DgaHhcMgrvA+LH4gXS0qzYfn+6fYNg2U+jK6qS1TKw== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=debbugs.gnu.org header.s=debbugs-gnu-org header.b="Qy/aN1Ru"; dkim=fail ("headers rsa verify failed") header.d=gnu.org header.s=fencepost-gnu-org header.b=WeQKn94b; dmarc=pass (policy=none) header.from=gnu.org; 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" 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 B4BDE659A2 for ; Thu, 05 Sep 2024 23:33:11 +0200 (CEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1smK66-0008Io-Hk; Thu, 05 Sep 2024 17:32:58 -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 1smK65-0008I3-59 for guix-patches@gnu.org; Thu, 05 Sep 2024 17:32:57 -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 1smK64-0002pO-Rc; Thu, 05 Sep 2024 17:32:56 -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=42LADpVb+ft8sCV1Q5a28K5KnD6jDcEyqilim5vg3Vo=; b=Qy/aN1RuVoMU3VqsYHnHEKJR8uhazABNNJFyi6mGYPPd9DLhq5YII5f04heju+/B6th6MO4A9+jFdkmCeZQwaSWp48/olZhAkmMauS9JH25tLj3pa48AxEPIYF6HU2BSJ51CqJ2bguWto2vc1ahvbarKcDJ8JY3QpnYESUcdynOAfKO6suR+XTOHbeiiOfxzyx+DGT9NiLyx4JbRdReNw0iL9ffdtECKu68yKmv9PHLa7oxSa4ZbUwOVCucs2T3iu8mWsDCcGB/OPPMQ52m+He3GPtO4al0E+G4aoZWWYIopAIc6f/3qjSyIsGCdr12QIFGqHAEd1R8KfqBrPyy3fg==; Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1smK78-00044l-5k; Thu, 05 Sep 2024 17:34:02 -0400 X-Loop: help-debbugs@gnu.org Subject: [bug#72840] [PATCH RFC v2] 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: Thu, 05 Sep 2024 21:34: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: patch To: 72840@debbugs.gnu.org Cc: Ludovic =?UTF-8?Q?Court=C3=A8s?= , 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.172557198215488 (code B ref 72840); Thu, 05 Sep 2024 21:34:02 +0000 Received: (at 72840) by debbugs.gnu.org; 5 Sep 2024 21:33:02 +0000 Received: from localhost ([127.0.0.1]:38413 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1smK69-00041T-LF for submit@debbugs.gnu.org; Thu, 05 Sep 2024 17:33:02 -0400 Received: from eggs.gnu.org ([209.51.188.92]:50332) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1smK67-00041G-LW for 72840@debbugs.gnu.org; Thu, 05 Sep 2024 17:33:00 -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 1smK4y-0002la-SF; Thu, 05 Sep 2024 17:31:48 -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=42LADpVb+ft8sCV1Q5a28K5KnD6jDcEyqilim5vg3Vo=; b=WeQKn94bt26w/097NGir jgksqhvECOjBFv/Y5vDpx+ruMo5B7s7FO7rkEEHpE+Jd377jLPm3lgJkBzfZSQdTsGVwcDSlopIG8 wLaC5JoIhCAP64GE378DXS0W8wwcdSzSBhJv94i+kDu/z5afrRpG/Bnwlqe5f+jMniXU9Cg+fcdIZ afMWbmgo1fF1DWm+OSNowWYcQG62Zl68apAFx1LJhaOTBS3CANQIt/M9mKHYriDISIBlwFkdGOGSi EnpZgXKug4aMDYrxKeCIg2++2Lav2WVbFwg0qo7y91VXuxiJcem61Hf/4MzOVotnpTQL2q+pYjiNN J6oNe6UetXptGA==; From: Ludovic =?UTF-8?Q?Court=C3=A8s?= Date: Thu, 5 Sep 2024 23:31:39 +0200 Message-ID: <53d897cec60ae13a22de486ba37604ab99e65fe8.1725571691.git.ludo@gnu.org> X-Mailer: git-send-email 2.45.2 In-Reply-To: <87frqd6bcu.fsf_-_@gnu.org> References: <87frqd6bcu.fsf_-_@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: -3.59 X-Spam-Score: -3.59 X-Migadu-Queue-Id: B4BDE659A2 X-Migadu-Scanner: mx11.migadu.com X-TUID: Hl9EvCQL91le * doc/contributing.texi (Deprecation Policy): New node. (Commit Access): Link to ‘package-removal-policy’. Change-Id: I5d095559920a3d9b791b5d919aab4e2f2a0c2dee --- doc/contributing.texi | 188 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 185 insertions(+), 3 deletions(-) Changes compared to v1: • Fixed typo reported by Florian; • Adding cross-reference in “Commit Access” section; • Typeset review/deprecation durations in boldface; • Clarified that the package removal policy also applies when removal is motivated by security reasons. Ludo’. diff --git a/doc/contributing.texi b/doc/contributing.texi index 73f7addbef..f8c2b5c245 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,185 @@ 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 +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 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 that their upstream developers have declared as having reached +``end of life'' or being unmaintained 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}. + +@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: 993d6d2e7be4dac738629c76a51058f4dc5bc449 -- 2.45.2