Next: Writing Documentation, Previous: Updating the Guix Package, Up: Contributing [Contents][Index]
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 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:
operating-system
and/or
home-environment
interfaces together with the service interfaces;
(guix ...)
modules.
These use cases form a spectrum with varying degrees of coupling—from “distant” to tightly coupled. Based on this insight, we define the following deprecation policies that we consider suitable for each of these levels.
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
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 guix
environment
by guix shell
, started in October
202153.
Because of the broad impact of such a change, we recommend conducting a user survey before enacting a plan.
When a package name changes, it must remain available under its old name
for at least one year. For example, go-ipfs
was renamed to
kubo
following a decision made upstream; to communicate the name
change to users, the package module provided this definition:
(define-public go-ipfs
(deprecated-package "go-ipfs" kubo))
That way, someone running guix install go-ipfs
or similar sees
a deprecation warning mentioning the new name.
Packages whose upstream developers have declared as having reached “end of life” or being unmaintained may be removed; likewise, packages that have been 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 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 (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 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
etc/news.scm
.
In the case of packages with many dependents and/or many users, an upgrade may be treated like the 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.
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
(guix deprecation)
mechanisms. For example, renaming of
murmur-configuration
to mumble-server-configuration
was
communicated through a series of definitions like this one:
(define-deprecated/public-alias
murmur-configuration
mumble-server-configuration)
Procedures slated for removal may be defined like this:
(define-deprecated (elogind-service #:key (config (elogind-configuration)))
elogind-service-type
(service elogind-service-type config))
Record fields, notably fields of service configuration records, must
follow a similar deprecation period. This is usually achieved through
ad hoc means though. For example, the hosts-file
field of
operating-system
was deprecated by adding a sanitized
property that would emit a warning:
(define-record-type* <operating-system> ;; … (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))
When deprecating interfaces in operating-system
,
home-environment
, (gnu services)
, or any popular service,
the deprecation must come with an entry in etc/news.scm
.
Core programming interfaces, in particular the (guix ...)
modules, may be relied on by a variety of external tools and channels.
Any incompatible change must be formally deprecated with
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 build-expression->derivation
procedure was
superseded by gexp->derivation
and remained available as a
deprecated symbol:
(define-deprecated (build-expression->derivation store name exp
#:key …)
gexp->derivation
…)
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.
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 guix-devel@gnu.org for any questions.
For more details on the guix shell
transition,
see
https://guix.gnu.org/en/blog/2021/from-guix-environment-to-guix-shell/.
Next: Writing Documentation, Previous: Updating the Guix Package, Up: Contributing [Contents][Index]