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 uJsLD5slzmY3ogAAqHPOHw:P1 (envelope-from ) for ; Tue, 27 Aug 2024 19:14:35 +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 uJsLD5slzmY3ogAAqHPOHw (envelope-from ) for ; Tue, 27 Aug 2024 21:14:35 +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=Z8QFQLMN; dkim=fail ("headers rsa verify failed") header.d=gnu.org header.s=fencepost-gnu-org header.b=jnMqw2rN; 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=1724786074; 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:list-id:list-help: list-unsubscribe:list-subscribe:list-post:dkim-signature; bh=O5/FG3x20uxwMrYiSYdQb/POiFZXq+vkLRhOuzuuP6A=; b=S3swTvLJ5+pR3jMyCPn7/YjqGRohQkCTlZSCip8DOTAd0ojGh15VJkJvMJtFrVzmwK3SH6 y13bCF4gLtA6W7tiSQHYgxsfydQ2+8f295dlVJfvYbI8knx8KNvPz5ksrCsKqOzsdhJWtO 5Nn7c4lThvnjGf4VXc18nQv8HbhmDJ7s1H7x0Mrg61SAUSmoJJtYx6dNzsXnWH/3xMVhku f+fhRQPqbiotwVqu2XIlv8UbwteBLjTR5v3q9/uqv/hsLCDB2XKgDOCqwIuelgpnqYpKqp pXQPHukabIeZUq/sHfsCE3/ublR8TzBCRNudc1labh115kzwZ8ROFm+cJ66EFw== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1724786074; a=rsa-sha256; cv=none; b=MUrWTn/ZdkiTOawwe5QqwA0OVdgV0+/ASDbznV1HSwWIGLEDsNDGpQU7Hx98LHTXUPcTA8 w9JFH5r0nTgjCWAjigPbOteXdrHLcpPC6So5rmQWADv51fmrNqcPaDVmBI+sHjIaM6Gzk0 hdsicEwNFoXzZ5oAoFhJdwQSNmjnYIb1jDOp0ExKg5HyP/XWAHdw4tQQu6z+3akgn+XyAr e9YKgnO8RYZ9d1zslcD39s1PoMQEs1TwMSghQ+rr1L+5m4MOD2LQfgVl1SWMh4Hvz9evXW +XtgZ6ENGnY9KZI7Hjf8ntmXCM2K/PbccZnFr6lV+W6EScVxKPiXL+tKDVaIBg== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=debbugs.gnu.org header.s=debbugs-gnu-org header.b=Z8QFQLMN; dkim=fail ("headers rsa verify failed") header.d=gnu.org header.s=fencepost-gnu-org header.b=jnMqw2rN; 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 C55013CA38 for ; Tue, 27 Aug 2024 21:14:34 +0200 (CEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1sj1dv-0005Zt-Es; Tue, 27 Aug 2024 15:14:15 -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 1sj1ds-0005ZW-H2 for guix-patches@gnu.org; Tue, 27 Aug 2024 15:14:12 -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 1sj1dq-0001od-OW; Tue, 27 Aug 2024 15:14:11 -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:Date:From:To:Subject; bh=O5/FG3x20uxwMrYiSYdQb/POiFZXq+vkLRhOuzuuP6A=; b=Z8QFQLMNJsd2aP+KtNfOrStaLCVNVtls6ZdyOHGAokqbIdadD3XZ9zDxrLIo3TrQvHYrKn+XIhH4TXb/coYqx2CkhVZjaHEM/75/EdlGLTntV12FlaSg4IVm1TMlk4vWmgKEO6Ibc7VOHgK3snPxRx6+tt8c0PpdD93Ww+C6uw38GIsxdvspMVw/vEINqcn6EX81HVmipQp/AyUjOQ/w9WSdS7LIkQ8GBP7s/bi34dQXIMx4Sl41nzVsp+WLGVtKZgY2EIarOWfqkCX20FhaKmy8+aQKQ+jwGJXpu20i+PKiFn/mktJtNT6pMUqX9TeJiptTum8K43EhZX1kdpBS2A==; Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1sj1eg-00066g-13; Tue, 27 Aug 2024 15:15:02 -0400 X-Loop: help-debbugs@gnu.org Subject: [bug#72839] [PATCH RFC] DRAFT 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, matt@excalamus.com, maxim.cournoyer@gmail.com, guix-patches@gnu.org Resent-Date: Tue, 27 Aug 2024 19:15:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 72839 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: 72839@debbugs.gnu.org Cc: Ludovic =?UTF-8?Q?Court=C3=A8s?= , Florian Pelz , Ludovic =?UTF-8?Q?Court=C3=A8s?= , Matthew Trzcinski , Maxim Cournoyer X-Debbugs-Original-To: guix-patches@gnu.org X-Debbugs-Original-Xcc: Florian Pelz , Ludovic =?UTF-8?Q?Court=C3=A8s?= , Matthew Trzcinski , Maxim Cournoyer Received: via spool by submit@debbugs.gnu.org id=B.172478608723428 (code B ref -1); Tue, 27 Aug 2024 19:15:01 +0000 Received: (at submit) by debbugs.gnu.org; 27 Aug 2024 19:14:47 +0000 Received: from localhost ([127.0.0.1]:47579 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1sj1eQ-00065n-Dj for submit@debbugs.gnu.org; Tue, 27 Aug 2024 15:14:47 -0400 Received: from lists.gnu.org ([209.51.188.17]:45144) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1sj1eL-00065d-Uv for submit@debbugs.gnu.org; Tue, 27 Aug 2024 15:14:45 -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 1sj1dT-0005XJ-E2 for guix-patches@gnu.org; Tue, 27 Aug 2024 15:13:48 -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 1sj1dS-0001nJ-1c; Tue, 27 Aug 2024 15:13:46 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-Version:Date:Subject:To:From:in-reply-to: references; bh=O5/FG3x20uxwMrYiSYdQb/POiFZXq+vkLRhOuzuuP6A=; b=jnMqw2rN1/YB6a Pz2ikt0uu7ffOjHinUPW+hh87d36SzuTeJEprrvOUi/VXHsDbP02KynUr6oMY7Tx8duMVY0Z3Rv0Z KJYjIPKqIDaOTtwnPTMSO6JjQJRpXlyHHsik3FxoNFicqxgN7rEoLBdYjwA3bjLuCDdU75mkWvV7o efMr23pS5QBPNWVWAThNbYrxt6hoxhx4syccnpb+8oEEPccDUJlJm6S0WWt12UvQlhDSM/o7KvOrf yljJqswAbBZZJYo4iNAjZQPbgRxjL0oSXZukUi5xXQFhBRHRDsVNyikpR4u8X8uogB5jdfW0b8vPM mbxXwiLHDU1G/ESlrCDg==; From: Ludovic =?UTF-8?Q?Court=C3=A8s?= Date: Tue, 27 Aug 2024 21:13:09 +0200 Message-ID: <80f8b603ecd73cb9f46b1ea43797e143f16d2f17.1724785788.git.ludo@gnu.org> X-Mailer: git-send-email 2.45.2 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: -0.78 X-Spam-Score: -0.78 X-Migadu-Queue-Id: C55013CA38 X-Migadu-Scanner: mx11.migadu.com X-TUID: BL4LDEJqVxjP DRAFT: This is a starting point submitted for discussion. * doc/contributing.texi (Deprecation Policy): New node. Change-Id: I5d095559920a3d9b791b5d919aab4e2f2a0c2dee --- doc/contributing.texi | 176 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 176 insertions(+) Hello! As promised long ago, here is an attempt to formalize a deprecation policy, based on current unwritten practice. Let’s discuss it with the goal of checking in an initial revision by next month. Thanks, Ludo’. diff --git a/doc/contributing.texi b/doc/contributing.texi index 73f7addbef..3c386f6510 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 @@ -3030,6 +3031,181 @@ 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 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 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. + +@item Package removal +Packages that their upstream developers have declared as having reach +``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 one-month review period of the patch +removing it. + +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 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 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: a1d367d6ee8c1783ef94cebbc5f2ae3b7a08078d -- 2.45.2