Channel branches: Difference between revisions

Revision as of 20:44, 22 December 2017

Nixpkgs is the git repository containing all packages and NixOS modules/expressions. Installing packages directly from the master branch of the Nixpkgs repo is possible, but risky, since git commits are merged into master before being heavily tested. That's where channels are useful.

A "channel" is a name for the latest "verified" git commits in Nixpkgs. Each channel has a different definition of what "verified" means. Each time a new git commit is verified, the channel declaring this verification gets updated. Contrary to a user of the git master branch, a channel user will benefit from both verified commits and binary packages from the binary cache.

Channels are reified as git branches in the nixpkgs-channels repository and as disk images in the channels webpage.

There are several channels, each with its own use case and verification phase.

The official channels

Channels can be broadly categorized into stable and unstable channels, and large and small channels:

Stable/unstable:
- Stable channels (nixos-17.09) provide conservative updates for fixing bugs and security vulnerabilities, but do not receive major updates after initial release. New stable channels are released every six months.
- Unstable channels (nixos-unstable, nixos-unstable-small) correspond to the main development branch of Nixpkgs, delivering the latest tested updates on a rolling basis.
Large/small:
- Large channels (nixos-17.09, nixos-unstable) provide binary builds for the full breadth of Nixpkgs.
- Small channels (nixos-17.09-small, nixos-unstable-small) are identical to large channels, but contain fewer binaries. This means they update faster, but require more to be built from source.

Most users will want the stable/large channel, currently nixos-17.09.

Like packages installed via nix-env, channels are managed at user-level. NixOS uses the channels set for the root user to update the system-wide configuration; channels set for other users control only the user environment for that user. If you wish to change the channel used by the system-level configuration (/etc/nixos/configuration.nix), ensure you run the correct nix-channel command as root:

Common nix-channel commands
Listing current channels	`nix-channel --list`
Adding a primary channel	`nix-channel --add https://nixos.org/channels/channel-name nixos`
Adding other channels	`nix-channel --add https://some.channel/url my-alias`
Remove a channel	`nix-channel --remove channel-alias`
Updating a channel	`nix-channel --update channel-alias`
Updating all channels	`nix-channel --update`

Note that updating channels won't cause a rebuild in itself; if you want to update channels and rebuild, you can run nixos rebuild --upgrade to do both in one step.

Channel update process

Each channel has a particular job at hydra.nixos.org which must succeed:

For NixOS: the trunk-combined/tested job, which contains some automated NixOS tests.
For nixos-small: the unstable-small/tested job.
For nixpkgs: the trunk/unstable job, which contains some critical release packages.

Once the job succeeds at a particular nixpkgs commit, cache.nixos.org will download binaries from hydra.nixos.org.

When the download completes, the channel updates.

To find out when a channel was last updated, check this page.

Unstable

The unstable channels (nixpkgs/unstable and nixos/unstable) are built off of the master branch.

Once a PR gets merged, a job is triggered in Hydra. This page lists the 15 most recent builds in the nixpkgs/unstable channel (with the left-most column being the most recent) along with each build's constituents. Constituents are critical packages.

A build is considered successful when both of the following two conditions are true:

All of the constituent jobs are green (meaning, the tests have succeeded)
All of the jobs in the corresponding evaluation have finished (with a success or a failure)

The evaluation for a build can be found on the build's page, following the "Part of" link in the "Summary" tab.

@@ Line 1: / Line 1: @@
-''Nix Channels'' are mechanisms for distributing Nix expressions as well as the associated binaries for them; a Nix channel corresponds to a repository in a conventional package management system. Official Nix channels are automatically updated once tests are passed in Nixpkgs' [[Hydra]] instance. It is also possible to create one's own Nix channels, but here we focus the official channels.
+Nixpkgs is the git repository containing all packages and NixOS modules/expressions. Installing packages directly from the master branch of the Nixpkgs repo is possible, but risky, since git commits are merged into master before being heavily tested. That's where channels are useful.
-To find out when a channel was last updated, check [https://howoldis.herokuapp.com/ this page].
+A "channel" is a name for the latest "verified" git commits in Nixpkgs. Each channel has a different definition of what "verified" means. Each time a new git commit is verified, the channel declaring this verification gets updated. Contrary to a user of the git master branch, a channel user will benefit from both verified commits and binary packages from the binary cache.
+Channels are reified as git branches in the [https://github.com/nixos/nixpkgs-channels nixpkgs-channels] repository and as disk images in the [https://nixos.org/channels/ channels webpage].
+There are several channels, each with its own use case and verification phase.
 == The official channels ==
-Packages for Nix, as well as modules for NixOS are distributed through a number of channels. These channels can be broadly categorized into ''stable'' and ''unstable'' channels, and ''large'' and ''small'' channels:
+Channels can be broadly categorized into ''stable'' and ''unstable'' channels, and ''large'' and ''small'' channels:
 * Stable/unstable:
@@ Line 14: / Line 18: @@
 ** Small channels (<code>nixos-17.09-small</code>, <code>nixos-unstable-small</code>) are identical to large channels, but contain fewer binaries. This means they update faster, but require more to be built from source.
-https://nixos.org/channels/ hosts the full list of the available official channels is available. Most users will want the stable/large channel, currently <code>nixos-17.09</code>.
+Most users will want the stable/large channel, currently <code>nixos-17.09</code>.
 Like packages installed via <code>nix-env</code>, channels are managed at user-level. NixOS uses the channels set for the <code>root</code> user to update the system-wide configuration; channels set for other users control only the user environment for that user. If you wish to change the channel used by the system-level configuration (<code>/etc/nixos/configuration.nix</code>), ensure you run the correct <code>nix-channel</code> command as root:
@@ Line 42: / Line 46: @@
 Note that updating channels won't cause a rebuild in itself; if you want to update channels and rebuild, you can run <code>nixos rebuild --upgrade</code> to do both in one step.
-== Channel release process ==
+== Channel update process ==
+Each channel has a particular job at [https://hydra.nixos.org hydra.nixos.org] which must succeed:
+* For NixOS: the [http://hydra.nixos.org/job/nixos/trunk-combined/tested trunk-combined/tested] job, which contains some automated NixOS tests.
+*  For nixos-small: the [http://hydra.nixos.org/job/nixos/unstable-small/tested unstable-small/tested] job.
+*  For nixpkgs: the [http://hydra.nixos.org/job/nixpkgs/trunk/unstable trunk/unstable] job, which contains some critical release packages.
+Once the job succeeds at a particular nixpkgs commit, cache.nixos.org will download binaries from [https://hydra.nixos.org hydra.nixos.org].
+When the download completes, the channel updates.
+To find out when a channel was last updated, check [https://howoldis.herokuapp.com/ this] page.
 === Unstable ===
@@ Line 48: / Line 64: @@
 The unstable channels (<code>nixpkgs/unstable</code> and <code>nixos/unstable</code>) are built off of the <code>master</code> branch.
-Once a PR gets merged, a job is triggered in [[Hydra]]. [https://hydra.nixos.org/job/nixpkgs/trunk/unstable#tabs-constituents This page] lists the 15 most recent builds in the <code>nixpkgs/unstable</code> channel, with the left-most column being the most recent.
+Once a PR gets merged, a job is triggered in [[Hydra]]. [https://hydra.nixos.org/job/nixpkgs/trunk/unstable#tabs-constituents This page] lists the 15 most recent builds in the <code>nixpkgs/unstable</code> channel (with the left-most column being the most recent) along with each build's constituents. Constituents are critical packages.
 A build is considered successful when both of the following two conditions are true:
-* All of the jobs in a column are green (meaning, the tests have succeeded)
+* All of the constituent jobs are green (meaning, the tests have succeeded)
 * All of the jobs in the corresponding evaluation have finished (with a success or a failure)
-The evaluation for a build can be found by clicking on the column heading, and then following the the "Part of" link in the "Summary" tab.
+The evaluation for a build can be found on the build's page, following the "Part of" link in the "Summary" tab.