From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp2.migadu.com ([2001:41d0:303:e224::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms13.migadu.com with LMTPS id MDy+Fgxt4WY6FgAAe85BDQ:P1 (envelope-from ) for ; Wed, 11 Sep 2024 10:12:28 +0000 Received: from aspmx1.migadu.com ([2001:41d0:303:e224::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp2.migadu.com with LMTPS id MDy+Fgxt4WY6FgAAe85BDQ (envelope-from ) for ; Wed, 11 Sep 2024 12:12:28 +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=dQDcYfuM; dkim=fail ("headers rsa verify failed") header.d=gnu.org header.s=fencepost-gnu-org header.b=W+P34Kjw; 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=1726049548; 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=utezWsfemszQx6e5D3hH/LfmPhO5v7laBfPDxVs4KpA=; b=GB9VdtYLa2AnMyrVlax5zNN/y1WWXkGE1ajLFMBnig40Dc5gJjgXHSIm/pwWHcZzE4aSmN PrKjWL4ZDRb5dPMo8m0n6as12NI74iMVXVhlRBU+kxMZS326MoxTC5G/BuOkvAkdW5m9z2 FhKINrglPDK+VenTyHG00W4PGC0z9M9BLwgy8UTgnDvH5aDsWoDKT/bpLeMkjaWOXN6sq+ iVNU1653AKdVjSaLVcP+8fyxuOLDhXhV0rpTPO2hnj7AGpUP88aQ1xvDEOnYKt0Xv5xsQq CWFrBUDIfXBBrY4J3iGQH8yCkfjBm4p/xgKN58AeG4km9DTr2/XRwgfcBNm7cA== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1726049548; a=rsa-sha256; cv=none; b=JbMXFtcF0WNpZAI01qg5wpTWRjR8bYyyHp3GeV/pSvBV329+gItyQou2Mm4X7wgpLK6sUr RBZuM35EywMNxkfYnQBPP5JmGrSs9LWg1SbM788Y7NIV8KUU8/GF9R6j9Rfpuw8d0hcJHX lHGVqePKEkOIUBxDwkTLokVZoSk7VdpO391oUBhdPqhlaUDjqQ0jgw0JGHoPu5j+7zo3Sp 4iA3Orb6DHkEvBhgChT9Fa+jskwy5cliG2n9tivLugPUwblnwvGH27NcyP40Z2zgn1W4A0 vDplZ8kr5zpK0KtQexH96HZpDag9j5dagIFef9onKGvsfyqtwnUApO603kiXog== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=debbugs.gnu.org header.s=debbugs-gnu-org header.b=dQDcYfuM; dkim=fail ("headers rsa verify failed") header.d=gnu.org header.s=fencepost-gnu-org header.b=W+P34Kjw; 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 906CA17238 for ; Wed, 11 Sep 2024 12:12:27 +0200 (CEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1soKKQ-0006YR-1P; Wed, 11 Sep 2024 06:12:02 -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 1soKKN-0006YG-V1 for guix-patches@gnu.org; Wed, 11 Sep 2024 06:12:00 -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 1soKKN-0000tQ-Au; Wed, 11 Sep 2024 06:11:59 -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=utezWsfemszQx6e5D3hH/LfmPhO5v7laBfPDxVs4KpA=; b=dQDcYfuMymmYFMNZmCnlvDVJGquF1awJCw16e0yo3BQCr1uZaHcHWeHShblsaAX67QdQ27wGSxWLPGObDIeu4lGdZO/Fp3PiQVqQNx15enmtibU+zim8kZHx0OluPJFygv81RTzxD/OazeRjz2zSLKaHNyZnFJJBoi/xnHtfLGBuqE+agGYJBDjB+QEBygzBGhqUDgrZKhGqN/MMJ6O1GMExpMG/2fHk0nQcnwhsgn9tbV5tHwSqdZwQ8bZugLv2VO1o+IHT1S87ZosMkf8X8EgyUIsb8FC0h2V3U0iVuiz8zX30eUiGK3Y38ewQMCgpXMFGBxKS7dJgabsjVw0fJA==; Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1soKKQ-0000XC-3c; Wed, 11 Sep 2024 06:12:02 -0400 X-Loop: help-debbugs@gnu.org Subject: [bug#72840] [PATCH RFC v3] 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: Wed, 11 Sep 2024 10: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: 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.17260495112032 (code B ref 72840); Wed, 11 Sep 2024 10:12:02 +0000 Received: (at 72840) by debbugs.gnu.org; 11 Sep 2024 10:11:51 +0000 Received: from localhost ([127.0.0.1]:37821 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1soKKE-0000Wh-Pp for submit@debbugs.gnu.org; Wed, 11 Sep 2024 06:11:51 -0400 Received: from eggs.gnu.org ([209.51.188.92]:37572) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1soKKC-0000WS-NX for 72840@debbugs.gnu.org; Wed, 11 Sep 2024 06:11:49 -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 1soKJz-0000pg-U2; Wed, 11 Sep 2024 06:11:36 -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=utezWsfemszQx6e5D3hH/LfmPhO5v7laBfPDxVs4KpA=; b=W+P34Kjwg6BDl/3+omDn 15NEI2aeCgAgvITyIu79NlCDVrxnqGE94uN9O74yXY9zFar4JIfbpMMVrD5JXoWdODl/eJRWgK502 1FTu9PgeOa25Gy/t4lrolB2Vh23sATDDEnUPBNs9G6Zuz6p6zbuGP2rmdrA0wPQENriBySCyGbkfA 8DGiRjSpDxAcYaKSMEP45Z9Zy+Lrbamg6qmUeIE31sQSXQv7igzyqKVP0rsmsE1qgUuO6VF/paG/m akTkugH1MUdliKH2P4oVdHsSN/QSbahIcSZz+NNiDlIpocNcelia7MdMtqemzLTc55I2dxUupNlUG m7xExIRX2MmFeg==; From: Ludovic =?UTF-8?Q?Court=C3=A8s?= Date: Wed, 11 Sep 2024 12:11:22 +0200 Message-ID: <902c544b5298617c2ed45af8d672130bc9b1a2e3.1726049102.git.ludo@gnu.org> X-Mailer: git-send-email 2.46.0 In-Reply-To: <8734m63c4f.fsf@gmail.com> References: <8734m63c4f.fsf@gmail.com> 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-Queue-Id: 906CA17238 X-Migadu-Scanner: mx12.migadu.com X-Migadu-Spam-Score: -6.59 X-Spam-Score: -6.59 X-TUID: eVokh1klJRXl * doc/contributing.texi (Deprecation Policy): New node. (Commit Access): Link to ‘package-removal-policy’. Change-Id: I5d095559920a3d9b791b5d919aab4e2f2a0c2dee --- doc/contributing.texi | 189 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 186 insertions(+), 3 deletions(-) Changes compared to v2: fixed typos reported by Maxim Cournoyer. diff --git a/doc/contributing.texi b/doc/contributing.texi index 73f7addbef..f713765357 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,186 @@ 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 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. 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: 637ca78f513fac15284403c0d3af64492ea832a1 -- 2.46.0