---

22.17 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 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:

• package management exclusively through the command line;
• advanced package management using the manifest and package interfaces;
• Home and System management, using the operating-system and/or home-environment interfaces together with the service interfaces;
• development or use of external tools that use programming interfaces such as the (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.

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 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 2021⁵⁶.

Because of the broad impact of such a change, we recommend conducting a user survey before enacting a plan.

Package name changes

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.

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 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.

Package upgrade

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.

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 (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 interfaces

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.