[bug#43482] [PATCH 0/3] doc: Reorder "Channels" section

[bug#43482] [PATCH 0/3] doc: Reorder "Channels" section

[zimoun]

Dear,

As discussed here [1], the Channels is modified to satisfy a more logical
order, at least mine. :-)

The patch 0003 can be hard to review.  Basically, I have moved the sections:

 5.6 Invoking @command{guix pull}
 5.7 Channels
   5.7.1 Specifying Additional Channels
   5.7.2 Using a Custom Guix Channel
   5.7.3 Replicating Guix
   5.7.4 Channel Authentication
   5.7.5 Primary URL
   5.7.6 Writing custom channels
   5.7.7 Package Modules in a Sub-directory
   5.7.8 Declaring Channel Dependencies
   5.7.9 Specifying Channel Authorizations
   5.7.10 Writing Channel News
 5.8 Invoking @command{guix time-machine}

And I did some minor tweaks trying to have user vs developer of channels.  Say
that from 5.7.1 to 5.7.5, the channel are collection of "variants". Then it
becomes "your own channel".

I added these words which deserve a better wording, I guess.

--8<---------------cut here---------------start------------->8---
Last, as a channel author, you may want to run an authenticated channel
(@pxref{Channel Authentication}), then @pxref{Specifying Channel
Authorizations} for details.
--8<---------------cut here---------------end--------------->8---

At the end of the section "Writing custom channels".

And after some thinking, I find better to have "guix pull" and time-machine
visible from Package Management section:
<https://guix.gnu.org/manual/devel/en/guix.html#Package-Management>.


Well, that is a start. :-)

[1] https://lists.gnu.org/archive/html/guix-devel/2020-09/msg00153.html


All the best,
simon

zimoun (3):
  doc: Update the master menu.
  doc: Add the "Channels" section menu.
  doc: Reorder the "Channels" section.

 doc/guix.texi | 353 +++++++++++++++++++++++++++++---------------------
 1 file changed, 202 insertions(+), 151 deletions(-)


base-commit: 679d5e6b3dcac4ee1f419c04b3719fead0bd9ee5
-- 
2.28.0

[bug#43482] [PATCH 1/3] doc: Update the master menu.

[zimoun]

* doc/guix.texi: Update the master menu.
---
 doc/guix.texi | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 88128a4b3a..5a1f2e3bc3 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -178,6 +178,7 @@ Installation
 * Setting Up the Daemon::       Preparing the build daemon's environment.
 * Invoking guix-daemon::        Running the build daemon.
 * Application Setup::           Application-specific setup.
+* Upgrading Guix::              Upgrading Guix and its build daemon.
 
 Setting Up the Daemon
 
@@ -197,8 +198,6 @@ System Installation
 * Installing Guix in a VM::     Guix System playground.
 * Building the Installation Image::  How this comes to be.
 
-Getting Started
-
 Manual Installation
 
 * Keyboard Layout and Networking and Partitioning:: Initial setup.
@@ -232,6 +231,7 @@ Development
 * Invoking guix environment::   Setting up development environments.
 * Invoking guix pack::          Creating software bundles.
 * The GCC toolchain::           Working with languages supported by GCC.
+* Invoking guix git authenticate:: Authenticating Git repositories.
 
 Programming Interface
 
@@ -300,6 +300,7 @@ Services
 * Scheduled Job Execution::     The mcron service.
 * Log Rotation::                The rottlog service.
 * Networking Services::         Network setup, SSH daemon, etc.
+* Unattended Upgrades::         Automated system upgrades.
 * X Window::                    Graphical display.
 * Printing Services::           Local and remote printer support.
 * Desktop Services::            D-Bus and desktop services.
@@ -310,6 +311,7 @@ Services
 * Telephony Services::          Telephony services.
 * Monitoring Services::         Monitoring services.
 * Kerberos Services::           Kerberos services.
+* LDAP Services::               LDAP services.
 * Web Services::                Web servers.
 * Certificate Services::        TLS certificates via Let's Encrypt.
 * DNS Services::                DNS daemons.
@@ -324,7 +326,7 @@ Services
 * PAM Mount Service::           Service to mount volumes when logging in.
 * Guix Services::               Services relating specifically to Guix.
 * Linux Services::              Services tied to the Linux kernel.
-* Hurd Services::               Services specific to a Hurd System.
+* Hurd Services::               Services specific for a Hurd System.
 * Miscellaneous Services::      Other services.
 
 Defining Services
@@ -334,6 +336,11 @@ Defining Services
 * Service Reference::           API reference.
 * Shepherd Services::           A particular type of service.
 
+Bootstrapping
+
+* Reduced Binary Seed Bootstrap::  A Bootstrap worthy of GNU.
+* Preparing to Use the Bootstrap Binaries:: Building that what matters most.
+
 @end detailmenu
 @end menu
 
-- 
2.28.0

[bug#43482] [PATCH 2/3] doc: Add the "Channels" section menu.

[zimoun]

* doc/guix.texi (Channels): Add the section menu.
---
 doc/guix.texi | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/doc/guix.texi b/doc/guix.texi
index 5a1f2e3bc3..f30faf257a 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -226,6 +226,18 @@ Substitutes
 * Substitution Failure::        What happens when substitution fails.
 * On Trusting Binaries::        How can you trust that binary blob?
 
+Channels
+
+* Channel Authentication::      How Guix verifies what it fetches.
+* Using a Custom Guix Channel:: Using a customized Guix.
+* Specifying Additional Channels:: Extending the package collection.
+* Declaring Channel Dependencies:: Declaring channel dependencies.
+* Package Modules in a Sub-directory:: Package Modules in a Sub-directory.
+* Specifying Channel Authorizations:: Specifying Channel Authorizations.
+* Primary URL::                 Distinguishing mirror to original.
+* Writing Channel News::        Communicating information to channel's users.
+* Replicating Guix::            Running the @emph{exact same} Guix.
+
 Development
 
 * Invoking guix environment::   Setting up development environments.
@@ -4206,6 +4218,19 @@ to pull from one or more channels.  In other words, channels can be used
 to @emph{customize} and to @emph{extend} Guix, as we will see below.
 Before that, some security considerations.
 
+@menu
+* Channel Authentication::      How Guix verifies what it fetches.
+* Using a Custom Guix Channel:: Using a customized Guix.
+* Specifying Additional Channels:: Extending the package collection.
+* Declaring Channel Dependencies:: Declaring channel dependencies.
+* Package Modules in a Sub-directory:: Package Modules in a Sub-directory.
+* Specifying Channel Authorizations:: Specifying Channel Authorizations.
+* Primary URL::                 Distinguishing mirror to original.
+* Writing Channel News::        Communicating information to channel's users.
+* Replicating Guix::            Running the @emph{exact same} Guix.
+@end menu
+
+@node Channel Authentication
 @subsection Channel Authentication
 
 @anchor{channel-authentication}
@@ -4245,6 +4270,7 @@ introduction from a trusted source since that is the root of your trust.
 
 If you're curious about the authentication mechanics, read on!
 
+@node Using a Custom Guix Channel
 @subsection Using a Custom Guix Channel
 
 The channel called @code{guix} specifies where Guix itself---its command-line
@@ -4265,6 +4291,7 @@ write in @code{~/.config/guix/channels.scm} this specification:
 From there on, @command{guix pull} will fetch code from the @code{super-hacks}
 branch of the repository at @code{example.org}.
 
+@node Specifying Additional Channels
 @subsection Specifying Additional Channels
 
 @cindex extending the package collection (channels)
@@ -4373,6 +4400,7 @@ my-tools)}, and you will be able to use it like any other module
 
 @cindex dependencies, channels
 @cindex meta-data, channels
+@node Declaring Channel Dependencies
 @subsection Declaring Channel Dependencies
 
 Channel authors may decide to augment a package collection provided by other
@@ -4413,6 +4441,7 @@ on channels that you don't control, and you should aim to keep the number of
 dependencies to a minimum.
 
 @cindex subdirectory, channels
+@node Package Modules in a Sub-directory
 @subsection Package Modules in a Sub-directory
 
 As a channel author, you may want to keep your channel modules in a
@@ -4426,6 +4455,7 @@ add a meta-data file @file{.guix-channel} that contains:
 @end lisp
 
 @cindex channel authorizations
+@node Specifying Channel Authorizations
 @subsection Specifying Channel Authorizations
 
 @anchor{channel-authorizations}
@@ -4526,6 +4556,7 @@ are considered authentic if and only if they are signed by a key present
 in the @file{.guix-authorizations} file of @emph{both} branches.
 
 @cindex primary URL, channels
+@node Primary URL
 @subsection Primary URL
 
 Channel authors can indicate the primary URL of their channel's Git
@@ -4548,6 +4579,7 @@ the official @code{guix} channel, for which @command{guix pull} ensures
 the code it fetches is authentic.
 
 @cindex news, for channels
+@node Writing Channel News
 @subsection Writing Channel News
 
 Channel authors may occasionally want to communicate to their users
@@ -4615,6 +4647,7 @@ xgettext -o news.po -l scheme -ken etc/news.txt
 To sum up, yes, you could use your channel as a blog.  But beware, this
 is @emph{not quite} what your users might expect.
 
+@node Replicating Guix
 @subsection Replicating Guix
 
 @cindex pinning, channels
-- 
2.28.0

[bug#43482] [PATCH 3/3] doc: Reorder the "Channels" section.

[zimoun]

* doc/guix.texi (Channels): Reorder the section.
Minor tweaks to keep uniformity.
Update the master menu.
---
 doc/guix.texi | 342 ++++++++++++++++++++++++++------------------------
 1 file changed, 177 insertions(+), 165 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index f30faf257a..015c8c9736 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -228,15 +228,16 @@ Substitutes
 
 Channels
 
+* Specifying Additional Channels::  Extending the package collection.
+* Using a Custom Guix Channel::  Using a customized Guix.
+* Replicating Guix::            Running the @emph{exact same} Guix.
 * Channel Authentication::      How Guix verifies what it fetches.
-* Using a Custom Guix Channel:: Using a customized Guix.
-* Specifying Additional Channels:: Extending the package collection.
-* Declaring Channel Dependencies:: Declaring channel dependencies.
-* Package Modules in a Sub-directory:: Package Modules in a Sub-directory.
-* Specifying Channel Authorizations:: Specifying Channel Authorizations.
 * Primary URL::                 Distinguishing mirror to original.
+* Writing custom channels::     How to setup your own channel.
+* Package Modules in a Sub-directory::  Specifying the channel's package modules location.
+* Declaring Channel Dependencies::  How to depend on other channels.
+* Specifying Channel Authorizations::  Defining channel authors authorizations.
 * Writing Channel News::        Communicating information to channel's users.
-* Replicating Guix::            Running the @emph{exact same} Guix.
 
 Development
 
@@ -4216,20 +4217,135 @@ customized by defining @dfn{channels} in the
 of a Git repository to be deployed, and @command{guix pull} can be instructed
 to pull from one or more channels.  In other words, channels can be used
 to @emph{customize} and to @emph{extend} Guix, as we will see below.
-Before that, some security considerations.
+Guix is able to take into account security concerns and deal with authenticated
+updates.
 
 @menu
+* Specifying Additional Channels::  Extending the package collection.
+* Using a Custom Guix Channel::  Using a customized Guix.
+* Replicating Guix::            Running the @emph{exact same} Guix.
 * Channel Authentication::      How Guix verifies what it fetches.
-* Using a Custom Guix Channel:: Using a customized Guix.
-* Specifying Additional Channels:: Extending the package collection.
-* Declaring Channel Dependencies:: Declaring channel dependencies.
-* Package Modules in a Sub-directory:: Package Modules in a Sub-directory.
-* Specifying Channel Authorizations:: Specifying Channel Authorizations.
 * Primary URL::                 Distinguishing mirror to original.
+* Writing custom channels::     How to setup your own channel.
+* Package Modules in a Sub-directory::  Specifying the channel's package modules location.
+* Declaring Channel Dependencies::  How to depend on other channels.
+* Specifying Channel Authorizations::  Defining channel authors authorizations.
 * Writing Channel News::        Communicating information to channel's users.
-* Replicating Guix::            Running the @emph{exact same} Guix.
 @end menu
 
+@node Specifying Additional Channels
+@subsection Specifying Additional Channels
+
+@cindex extending the package collection (channels)
+@cindex variant packages (channels)
+You can specify @emph{additional channels} to pull from. To use a channel, write
+@code{~/.config/guix/channels.scm} to instruct @command{guix pull} to pull from it
+@emph{in addition} to the default Guix channel(s):
+
+@vindex %default-channels
+@lisp
+;; Add variant packages to those Guix provides.
+(cons (channel
+        (name 'variant-packages)
+        (url "https://example.org/variant-packages.git"))
+      %default-channels)
+@end lisp
+
+@noindent
+Note that the snippet above is (as always!)@: Scheme code; we use @code{cons} to
+add a channel the list of channels that the variable @code{%default-channels}
+is bound to (@pxref{Pairs, @code{cons} and lists,, guile, GNU Guile Reference
+Manual}).  With this file in place, @command{guix pull} builds not only Guix
+but also the package modules from your own repository.  The result in
+@file{~/.config/guix/current} is the union of Guix with your own package
+modules:
+
+@example
+$ guix pull --list-generations
+@dots{}
+Generation 19	Aug 27 2018 16:20:48
+  guix d894ab8
+    repository URL: https://git.savannah.gnu.org/git/guix.git
+    branch: master
+    commit: d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300
+  variant-packages dd3df5e
+    repository URL: https://example.org/variant-packages.git
+    branch: master
+    commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb
+  11 new packages: variant-gimp, variant-emacs-with-cool-features, @dots{}
+  4 packages upgraded: emacs-racket-mode@@0.0.2-2.1b78827, @dots{}
+@end example
+
+@noindent
+The output of @command{guix pull} above shows that Generation@tie{}19 includes
+both Guix and packages from the @code{variant-personal-packages} channel.  Among
+the new and upgraded packages that are listed, some like @code{variant-gimp} and
+@code{variant-emacs-with-cool-features} might come from
+@code{variant-packages}, while others come from the Guix default channel.
+
+@node Using a Custom Guix Channel
+@subsection Using a Custom Guix Channel
+
+The channel called @code{guix} specifies where Guix itself---its command-line
+tools as well as its package collection---should be downloaded.  For instance,
+suppose you want to update from another copy of the Guix repository at
+@code{example.org}, and specifically the @code{super-hacks} branch, you can
+write in @code{~/.config/guix/channels.scm} this specification:
+
+@lisp
+;; Tell 'guix pull' to use another repo.
+(list (channel
+        (name 'guix)
+        (url "https://example.org/another-guix.git")
+        (branch "super-hacks")))
+@end lisp
+
+@noindent
+From there on, @command{guix pull} will fetch code from the @code{super-hacks}
+branch of the repository at @code{example.org}.  The authentication concern is
+addressed below ((@pxref{Channel  Authentication}).
+
+@node Replicating Guix
+@subsection Replicating Guix
+
+@cindex pinning, channels
+@cindex replicating Guix
+@cindex reproducibility, of Guix
+The @command{guix pull --list-generations} output above shows precisely which
+commits were used to build this instance of Guix.  We can thus replicate it,
+say, on another machine, by providing a channel specification in
+@file{~/.config/guix/channels.scm} that is ``pinned'' to these commits:
+
+@lisp
+;; Deploy specific commits of my channels of interest.
+(list (channel
+       (name 'guix)
+       (url "https://git.savannah.gnu.org/git/guix.git")
+       (commit "6298c3ffd9654d3231a6f25390b056483e8f407c"))
+      (channel
+       (name 'variant-packages)
+       (url "https://example.org/variant-packages.git")
+       (commit "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb")))
+@end lisp
+
+The @command{guix describe --format=channels} command can even generate this
+list of channels directly (@pxref{Invoking guix describe}).  The resulting
+file can be used with the -C options of @command{guix pull}
+(@pxref{Invoking guix pull}) or @command{guix time-machine}
+(@pxref{Invoking guix time-machine}).
+
+At this point the two machines run the @emph{exact same Guix}, with access to
+the @emph{exact same packages}.  The output of @command{guix build gimp} on
+one machine will be exactly the same, bit for bit, as the output of the same
+command on the other machine.  It also means both machines have access to all
+the source code of Guix and, transitively, to all the source code of every
+package it defines.
+
+This gives you super powers, allowing you to track the provenance of binary
+artifacts with very fine grain, and to reproduce software environments at
+will---some sort of ``meta reproducibility'' capabilities, if you will.
+@xref{Inferiors}, for another way to take advantage of these super powers.
+
 @node Channel Authentication
 @subsection Channel Authentication
 
@@ -4248,8 +4364,8 @@ along these lines:
 
 @lisp
 (channel
-  (name 'my-channel)
-  (url "https://example.org/my-channel.git")
+  (name 'some-channel)
+  (url "https://example.org/some-channel.git")
   (introduction
    (make-channel-introduction
     "6f0d8cc0d88abb59c324b2990bfee2876016bb86"
@@ -4270,40 +4386,41 @@ introduction from a trusted source since that is the root of your trust.
 
 If you're curious about the authentication mechanics, read on!
 
-@node Using a Custom Guix Channel
-@subsection Using a Custom Guix Channel
+@cindex primary URL, channels
+@node Primary URL
+@subsection Primary URL
 
-The channel called @code{guix} specifies where Guix itself---its command-line
-tools as well as its package collection---should be downloaded.  For instance,
-suppose you want to update from your own copy of the Guix repository at
-@code{example.org}, and specifically the @code{super-hacks} branch, you can
-write in @code{~/.config/guix/channels.scm} this specification:
+Channel authors can indicate the primary URL of their channel's Git
+repository in the @file{.guix-channel} file, like so:
 
 @lisp
-;; Tell 'guix pull' to use my own repo.
-(list (channel
-        (name 'guix)
-        (url "https://example.org/my-guix.git")
-        (branch "super-hacks")))
+(channel
+  (version 0)
+  (url "https://example.org/guix.git"))
 @end lisp
 
-@noindent
-From there on, @command{guix pull} will fetch code from the @code{super-hacks}
-branch of the repository at @code{example.org}.
+This allows @command{guix pull} to determine whether it is pulling code
+from a mirror of the channel; when that is the case, it warns the user
+that the mirror might be stale and displays the primary URL.  That way,
+users cannot be tricked into fetching code from a stale mirror that does
+not receive security updates.
 
-@node Specifying Additional Channels
-@subsection Specifying Additional Channels
+This feature only makes sense for authenticated repositories, such as
+the official @code{guix} channel, for which @command{guix pull} ensures
+the code it fetches is authentic.
 
-@cindex extending the package collection (channels)
 @cindex personal packages (channels)
 @cindex channels, for personal packages
-You can also specify @emph{additional channels} to pull from.  Let's say you
-have a bunch of custom package variants or personal packages that you think
-would make little sense to contribute to the Guix project, but would like to
-have these packages transparently available to you at the command line.  You
-would first write modules containing those package definitions (@pxref{Package
-Modules}), maintain them in a Git repository, and then you and anyone else can
-use it as an additional channel to get packages from.  Neat, no?
+@node Writing custom channels
+@subsection Writing custom channels
+
+Let's say you have a bunch of custom package variants or personal packages
+that you think would make little sense to contribute to the Guix project, but
+would like to have these packages transparently available to you at the
+command line.  You would first write modules containing those package
+definitions (@pxref{Package Modules}), maintain them in a Git repository, and
+then you and anyone else can use it as an additional channel to get packages
+from.  Neat, no?
 
 @c What follows stems from discussions at
 @c <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22629#134> as well as
@@ -4342,51 +4459,6 @@ share your improvements, which are basic tenets of
 email us at @email{guix-devel@@gnu.org} if you'd like to discuss this.
 @end quotation
 
-To use a channel, write @code{~/.config/guix/channels.scm} to instruct
-@command{guix pull} to pull from it @emph{in addition} to the default Guix
-channel(s):
-
-@vindex %default-channels
-@lisp
-;; Add my personal packages to those Guix provides.
-(cons (channel
-        (name 'my-personal-packages)
-        (url "https://example.org/personal-packages.git"))
-      %default-channels)
-@end lisp
-
-@noindent
-Note that the snippet above is (as always!)@: Scheme code; we use @code{cons} to
-add a channel the list of channels that the variable @code{%default-channels}
-is bound to (@pxref{Pairs, @code{cons} and lists,, guile, GNU Guile Reference
-Manual}).  With this file in place, @command{guix pull} builds not only Guix
-but also the package modules from your own repository.  The result in
-@file{~/.config/guix/current} is the union of Guix with your own package
-modules:
-
-@example
-$ guix pull --list-generations
-@dots{}
-Generation 19	Aug 27 2018 16:20:48
-  guix d894ab8
-    repository URL: https://git.savannah.gnu.org/git/guix.git
-    branch: master
-    commit: d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300
-  my-personal-packages dd3df5e
-    repository URL: https://example.org/personal-packages.git
-    branch: master
-    commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb
-  11 new packages: my-gimp, my-emacs-with-cool-features, @dots{}
-  4 packages upgraded: emacs-racket-mode@@0.0.2-2.1b78827, @dots{}
-@end example
-
-@noindent
-The output of @command{guix pull} above shows that Generation@tie{}19 includes
-both Guix and packages from the @code{my-personal-packages} channel.  Among
-the new and upgraded packages that are listed, some like @code{my-gimp} and
-@code{my-emacs-with-cool-features} might come from
-@code{my-personal-packages}, while others come from the Guix default channel.
-
 To create a channel, create a Git repository containing your own package
 modules and make it available.  The repository can contain anything, but a
 useful channel will contain Guile modules that export packages.  Once you
@@ -4398,6 +4470,24 @@ module, then the module will be available under the name @code{(my-packages
 my-tools)}, and you will be able to use it like any other module
 (@pxref{Modules,,, guile, GNU Guile Reference Manual}).
 
+Last, as a channel author, you may want to run an authenticated channel
+(@pxref{Channel Authentication}), then @pxref{Specifying Channel
+Authorizations} for details.
+
+@cindex subdirectory, channels
+@node Package Modules in a Sub-directory
+@subsection Package Modules in a Sub-directory
+
+As a channel author, you may want to keep your channel modules in a
+sub-directory.  If your modules are in the sub-directory @file{guix}, you must
+add a meta-data file @file{.guix-channel} that contains:
+
+@lisp
+(channel
+  (version 0)
+  (directory "guix"))
+@end lisp
+
 @cindex dependencies, channels
 @cindex meta-data, channels
 @node Declaring Channel Dependencies
@@ -4415,7 +4505,7 @@ The meta-data file should contain a simple S-expression like this:
  (version 0)
  (dependencies
   (channel
-   (name some-collection)
+   (name 'some-collection)
    (url "https://example.org/first-collection.git")
 
    ;; The 'introduction' bit below is optional: you would
@@ -4426,7 +4516,7 @@ The meta-data file should contain a simple S-expression like this:
       (commit "a8883b58dc82e167c96506cf05095f37c2c2c6cd")
       (signer "CABB A931 C0FF EEC6 900D  0CFB 090B 1199 3D9A EBB5"))))
   (channel
-   (name some-other-collection)
+   (name 'some-other-collection)
    (url "https://example.org/second-collection.git")
    (branch "testing"))))
 @end lisp
@@ -4440,20 +4530,6 @@ For the sake of reliability and maintainability, you should avoid dependencies
 on channels that you don't control, and you should aim to keep the number of
 dependencies to a minimum.
 
-@cindex subdirectory, channels
-@node Package Modules in a Sub-directory
-@subsection Package Modules in a Sub-directory
-
-As a channel author, you may want to keep your channel modules in a
-sub-directory.  If your modules are in the sub-directory @file{guix}, you must
-add a meta-data file @file{.guix-channel} that contains:
-
-@lisp
-(channel
-  (version 0)
-  (directory "guix"))
-@end lisp
-
 @cindex channel authorizations
 @node Specifying Channel Authorizations
 @subsection Specifying Channel Authorizations
@@ -4555,29 +4631,6 @@ authentication!  Pay attention to merges in particular: merge commits
 are considered authentic if and only if they are signed by a key present
 in the @file{.guix-authorizations} file of @emph{both} branches.
 
-@cindex primary URL, channels
-@node Primary URL
-@subsection Primary URL
-
-Channel authors can indicate the primary URL of their channel's Git
-repository in the @file{.guix-channel} file, like so:
-
-@lisp
-(channel
-  (version 0)
-  (url "https://example.org/guix.git"))
-@end lisp
-
-This allows @command{guix pull} to determine whether it is pulling code
-from a mirror of the channel; when that is the case, it warns the user
-that the mirror might be stale and displays the primary URL.  That way,
-users cannot be tricked into fetching code from a stale mirror that does
-not receive security updates.
-
-This feature only makes sense for authenticated repositories, such as
-the official @code{guix} channel, for which @command{guix pull} ensures
-the code it fetches is authentic.
-
 @cindex news, for channels
 @node Writing Channel News
 @subsection Writing Channel News
@@ -4647,47 +4700,6 @@ xgettext -o news.po -l scheme -ken etc/news.txt
 To sum up, yes, you could use your channel as a blog.  But beware, this
 is @emph{not quite} what your users might expect.
 
-@node Replicating Guix
-@subsection Replicating Guix
-
-@cindex pinning, channels
-@cindex replicating Guix
-@cindex reproducibility, of Guix
-The @command{guix pull --list-generations} output above shows precisely which
-commits were used to build this instance of Guix.  We can thus replicate it,
-say, on another machine, by providing a channel specification in
-@file{~/.config/guix/channels.scm} that is ``pinned'' to these commits:
-
-@lisp
-;; Deploy specific commits of my channels of interest.
-(list (channel
-       (name 'guix)
-       (url "https://git.savannah.gnu.org/git/guix.git")
-       (commit "6298c3ffd9654d3231a6f25390b056483e8f407c"))
-      (channel
-       (name 'my-personal-packages)
-       (url "https://example.org/personal-packages.git")
-       (commit "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb")))
-@end lisp
-
-The @command{guix describe --format=channels} command can even generate this
-list of channels directly (@pxref{Invoking guix describe}).  The resulting
-file can be used with the -C options of @command{guix pull}
-(@pxref{Invoking guix pull}) or @command{guix time-machine}
-(@pxref{Invoking guix time-machine}).
-
-At this point the two machines run the @emph{exact same Guix}, with access to
-the @emph{exact same packages}.  The output of @command{guix build gimp} on
-one machine will be exactly the same, bit for bit, as the output of the same
-command on the other machine.  It also means both machines have access to all
-the source code of Guix and, transitively, to all the source code of every
-package it defines.
-
-This gives you super powers, allowing you to track the provenance of binary
-artifacts with very fine grain, and to reproduce software environments at
-will---some sort of ``meta reproducibility'' capabilities, if you will.
-@xref{Inferiors}, for another way to take advantage of these super powers.
-
 @node Invoking guix time-machine
 @section Invoking @command{guix time-machine}
 
-- 
2.28.0

[bug#43482] [PATCH 1/3] doc: Update the master menu.

[Ludovic Courtès]

Hi,

zimoun <zimon.toutoune@gmail.com> skribis:

> * doc/guix.texi: Update the master menu.

LGTM!

How come it got this much out of sync?  How did you update it?  IME the
Emacs thingie gets confused when some but not all the top-level nodes
are in separate files.

Thanks,
Ludo’.

[bug#43482] [PATCH 2/3] doc: Add the "Channels" section menu.

[Ludovic Courtès]

zimoun <zimon.toutoune@gmail.com> skribis:

> * doc/guix.texi (Channels): Add the section menu.

[...]

> +@node Channel Authentication
>  @subsection Channel Authentication

What I had in mind was also to move everything one level higher:
@section becomes @chapter, @subsection becomes @section, etc.

WDYT?

[bug#43482] [PATCH 3/3] doc: Reorder the "Channels" section.

[Ludovic Courtès]

zimoun <zimon.toutoune@gmail.com> skribis:

> * doc/guix.texi (Channels): Reorder the section.
> Minor tweaks to keep uniformity.
> Update the master menu.

It would be nice if you could better describe what’s moved where since
looking at the diff doesn’t help understand it.

> +@node Writing custom channels
> +@subsection Writing custom channels

Should be “Writing Custom Channels”.

Maybe “Creating a Channel” is more to the point actually?

>  To create a channel, create a Git repository containing your own package
>  modules and make it available.  The repository can contain anything, but a
>  useful channel will contain Guile modules that export packages.  Once you
> @@ -4398,6 +4470,24 @@ module, then the module will be available under the name @code{(my-packages
>  my-tools)}, and you will be able to use it like any other module
>  (@pxref{Modules,,, guile, GNU Guile Reference Manual}).
>  
> +Last, as a channel author, you may want to run an authenticated channel
> +(@pxref{Channel Authentication}), then @pxref{Specifying Channel
> +Authorizations} for details.

Maybe something like:

  As a channel author, consider bundling authentication material with
  your channel so that users can authenticate it.  @xref{Channel
  Authentication}, and @ref{Specifying Channel Authorizations}, for
  info on how to do it.

(Note: @pxref cannot be used in the middle of a sentence like you did
above.  I always end up re-reading the Texinfo manual to find which
cross-reference command to use in which context…)

Could you send updated patches?

Thanks!

Ludo’.

[bug#43482] [PATCH 2/3] doc: Add the "Channels" section menu.

[zimoun]

On Thu, 24 Sep 2020 at 16:52, Ludovic Courtès <ludo@gnu.org> wrote:

> > +@node Channel Authentication
> >  @subsection Channel Authentication
>
> What I had in mind was also to move everything one level higher:
> @section becomes @chapter, @subsection becomes @section, etc.

I had that in mind too.  After I did the change (subsection->section,
etc.), then I was not convinced, so I just added the '@node'.
Concretely, I do not have a strong opinion.  Let's rebase with this
big move. :-)

However, moving "guix pull" and "guix time-machine" to this section
does not appear to me "logical" and should stay under Package
management.  Especially with the "one level higher" move.  WDYT?

Cheers,
simon

[bug#43482] [PATCH 3/3] doc: Reorder the "Channels" section.

[zimoun]

Hi,

Thank you for the review.

On Thu, 24 Sep 2020 at 16:59, Ludovic Courtès <ludo@gnu.org> wrote:

> > * doc/guix.texi (Channels): Reorder the section.
> > Minor tweaks to keep uniformity.
> > Update the master menu.
>
> It would be nice if you could better describe what’s moved where since
> looking at the diff doesn’t help understand it.

I will try to do my best. :-)


> > +@node Writing custom channels
> > +@subsection Writing custom channels
>
> Should be “Writing Custom Channels”.
>
> Maybe “Creating a Channel” is more to the point actually?

Ok.


> > +Last, as a channel author, you may want to run an authenticated channel
> > +(@pxref{Channel Authentication}), then @pxref{Specifying Channel
> > +Authorizations} for details.
>
> Maybe something like:
>
>   As a channel author, consider bundling authentication material with
>   your channel so that users can authenticate it.  @xref{Channel
>   Authentication}, and @ref{Specifying Channel Authorizations}, for
>   info on how to do it.

Ok.

> (Note: @pxref cannot be used in the middle of a sentence like you did
> above.  I always end up re-reading the Texinfo manual to find which
> cross-reference command to use in which context…)

Thanks for the explanations.


> Could you send updated patches?

Ok.


Cheers,
simon

[bug#43482] [PATCH 1/3] doc: Update the master menu.

[zimoun]

On Thu, 24 Sep 2020 at 16:51, Ludovic Courtès <ludo@gnu.org> wrote:

> How come it got this much out of sync?  How did you update it?  IME the
> Emacs thingie gets confused when some but not all the top-level nodes
> are in separate files.

I do not remember exactly how.  Well, I have used the 'menu-bar' since
I never remember the TexInfo keys.
Then, I tried 'texinfo-master-menu' and  'texinfo-every-node-update'
and 'texinfo-all-menus-update' and manually checked with Magit the
diff.

For example, this commit b460ba7992 adds one node but does not update
the master menu; the TeXInfo workflow is a bit tedious and the mistake
always happens somehow.

Cheers,
simon

[bug#43482] [PATCH 2/3] doc: Add the "Channels" section menu.

[Ludovic Courtès]

Hi,

zimoun <zimon.toutoune@gmail.com> skribis:

> On Thu, 24 Sep 2020 at 16:52, Ludovic Courtès <ludo@gnu.org> wrote:
>
>> > +@node Channel Authentication
>> >  @subsection Channel Authentication
>>
>> What I had in mind was also to move everything one level higher:
>> @section becomes @chapter, @subsection becomes @section, etc.
>
> I had that in mind too.  After I did the change (subsection->section,
> etc.), then I was not convinced, so I just added the '@node'.

I think moving one level higher can help.  More generally, I think it’s
a bad sign when a manual as few chapters and many subsubsubsections; it
makes it harder to see what the main topics are.  It’s a problem we have
here (the Guile manual is worse in that respect :-)).

> However, moving "guix pull" and "guix time-machine" to this section
> does not appear to me "logical" and should stay under Package
> management.  Especially with the "one level higher" move.  WDYT?

We’ll see that later.  :-)

Thanks,
Ludo’.

[bug#43482] [PATCH v2 1/2] doc: Update the master menu.

[zimoun]

* doc/guix.texi: Update the master menu.
---
 doc/guix.texi | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index a66ab82b31..bc72373d80 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -179,6 +179,7 @@ Installation
 * Setting Up the Daemon::       Preparing the build daemon's environment.
 * Invoking guix-daemon::        Running the build daemon.
 * Application Setup::           Application-specific setup.
+* Upgrading Guix::              Upgrading Guix and its build daemon.
 
 Setting Up the Daemon
 
@@ -198,8 +199,6 @@ System Installation
 * Installing Guix in a VM::     Guix System playground.
 * Building the Installation Image::  How this comes to be.
 
-Getting Started
-
 Manual Installation
 
 * Keyboard Layout and Networking and Partitioning:: Initial setup.
@@ -233,6 +232,7 @@ Development
 * Invoking guix environment::   Setting up development environments.
 * Invoking guix pack::          Creating software bundles.
 * The GCC toolchain::           Working with languages supported by GCC.
+* Invoking guix git authenticate:: Authenticating Git repositories.
 
 Programming Interface
 
@@ -301,6 +301,7 @@ Services
 * Scheduled Job Execution::     The mcron service.
 * Log Rotation::                The rottlog service.
 * Networking Services::         Network setup, SSH daemon, etc.
+* Unattended Upgrades::         Automated system upgrades.
 * X Window::                    Graphical display.
 * Printing Services::           Local and remote printer support.
 * Desktop Services::            D-Bus and desktop services.
@@ -311,6 +312,7 @@ Services
 * Telephony Services::          Telephony services.
 * Monitoring Services::         Monitoring services.
 * Kerberos Services::           Kerberos services.
+* LDAP Services::               LDAP services.
 * Web Services::                Web servers.
 * Certificate Services::        TLS certificates via Let's Encrypt.
 * DNS Services::                DNS daemons.
@@ -325,7 +327,7 @@ Services
 * PAM Mount Service::           Service to mount volumes when logging in.
 * Guix Services::               Services relating specifically to Guix.
 * Linux Services::              Services tied to the Linux kernel.
-* Hurd Services::               Services specific to a Hurd System.
+* Hurd Services::               Services specific for a Hurd System.
 * Miscellaneous Services::      Other services.
 
 Defining Services
@@ -335,6 +337,11 @@ Defining Services
 * Service Reference::           API reference.
 * Shepherd Services::           A particular type of service.
 
+Bootstrapping
+
+* Reduced Binary Seed Bootstrap::  A Bootstrap worthy of GNU.
+* Preparing to Use the Bootstrap Binaries:: Building that what matters most.
+
 @end detailmenu
 @end menu
 

base-commit: 3e5ed76df5ba12be22c6360abd83f328c3613ae0
-- 
2.28.0

[bug#43482] [PATCH v2 2/2] doc: Promote "Channels" as chapter and reorder.

[zimoun]

The sectioning becomes:

1.  Specifying Additional Channels     (was 3.)
2.  Using a Custom Guix Channel        (was 2.)
3.  Replicating Guix                   (was 9.)
4.  Channel Authentication             (was 1.)
5.  Primary URL                        (was 7.)
6.  Creating a Channel                 (reworded)
7.  Package Modules in a Sub-directory (was 5.)
8.  Declaring Channel Dependencies     (was 4.)
9.  Specifying Channel Authorizations  (was 6.)
10. Writing Channel News               (was 8.)

* doc/guix.texi (Channels): Move section to chapter.
Reorder the chapter.
Minor tweaks to keep uniformity.
Update the master menu.
---
 doc/guix.texi | 1587 +++++++++++++++++++++++++------------------------
 1 file changed, 817 insertions(+), 770 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index bc72373d80..ef10785316 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -147,6 +147,7 @@ Project}.
 * System Installation::         Installing the whole operating system.
 * Getting Started::             Your first steps.
 * Package Management::          Package installation, upgrade, etc.
+* Channels::                    Customizing the package collection.
 * Development::                 Guix-aided software development.
 * Programming Interface::       Using Guix in Scheme.
 * Utilities::                   Package management commands.
@@ -212,7 +213,6 @@ Package Management
 * Packages with Multiple Outputs::  Single source package, multiple outputs.
 * Invoking guix gc::            Running the garbage collector.
 * Invoking guix pull::          Fetching the latest Guix and distribution.
-* Channels::                    Customizing the package collection.
 * Invoking guix time-machine::  Running an older revision of Guix.
 * Inferiors::                   Interacting with another revision of Guix.
 * Invoking guix describe::      Display information about your Guix revision.
@@ -227,6 +227,19 @@ Substitutes
 * Substitution Failure::        What happens when substitution fails.
 * On Trusting Binaries::        How can you trust that binary blob?
 
+Channels
+
+* Specifying Additional Channels::  Extending the package collection.
+* Using a Custom Guix Channel::  Using a customized Guix.
+* Replicating Guix::            Running the @emph{exact same} Guix.
+* Channel Authentication::      How Guix verifies what it fetches.
+* Primary URL::                 Distinguishing mirror to original.
+* Creating a Channel::          How to write your custom channel.
+* Package Modules in a Sub-directory::  Specifying the channel's package modules location.
+* Declaring Channel Dependencies::  How to depend on other channels.
+* Specifying Channel Authorizations::  Defining channel authors authorizations.
+* Writing Channel News::        Communicating information to channel's users.
+
 Development
 
 * Invoking guix environment::   Setting up development environments.
@@ -2812,7 +2825,6 @@ guix install emacs-guix
 * Packages with Multiple Outputs::  Single source package, multiple outputs.
 * Invoking guix gc::            Running the garbage collector.
 * Invoking guix pull::          Fetching the latest Guix and distribution.
-* Channels::                    Customizing the package collection.
 * Invoking guix time-machine::  Running an older revision of Guix.
 * Inferiors::                   Interacting with another revision of Guix.
 * Invoking guix describe::      Display information about your Guix revision.
@@ -4189,937 +4201,972 @@ information.
 In addition, @command{guix pull} supports all the common build options
 (@pxref{Common Build Options}).
 
-@node Channels
-@section Channels
-
-@cindex channels
-@cindex @file{channels.scm}, configuration file
-@cindex configuration file for channels
-@cindex @command{guix pull}, configuration file
-@cindex configuration of @command{guix pull}
-Guix and its package collection are updated by running @command{guix pull}
-(@pxref{Invoking guix pull}).  By default @command{guix pull} downloads and
-deploys Guix itself from the official GNU@tie{}Guix repository.  This can be
-customized by defining @dfn{channels} in the
-@file{~/.config/guix/channels.scm} file.  A channel specifies a URL and branch
-of a Git repository to be deployed, and @command{guix pull} can be instructed
-to pull from one or more channels.  In other words, channels can be used
-to @emph{customize} and to @emph{extend} Guix, as we will see below.
-Before that, some security considerations.
+@node Invoking guix time-machine
+@section Invoking @command{guix time-machine}
 
-@subsection Channel Authentication
+@cindex @command{guix time-machine}
+@cindex pinning, channels
+@cindex replicating Guix
+@cindex reproducibility, of Guix
 
-@anchor{channel-authentication}
-@cindex authentication, of channel code
-The @command{guix pull} and @command{guix time-machine} commands
-@dfn{authenticate} the code retrieved from channels: they make sure each
-commit that is fetched is signed by an authorized developer.  The goal
-is to protect from unauthorized modifications to the channel that would
-lead users to run malicious code.
+The @command{guix time-machine} command provides access to other
+revisions of Guix, for example to install older versions of packages,
+or to reproduce a computation in an identical environment.  The revision
+of Guix to be used is defined by a commit or by a channel
+description file created by @command{guix describe}
+(@pxref{Invoking guix describe}).
 
-As a user, you must provide a @dfn{channel introduction} in your
-channels file so that Guix knows how to authenticate its first commit.
-A channel specification, including its introduction, looks something
-along these lines:
+The general syntax is:
 
-@lisp
-(channel
-  (name 'my-channel)
-  (url "https://example.org/my-channel.git")
-  (introduction
-   (make-channel-introduction
-    "6f0d8cc0d88abb59c324b2990bfee2876016bb86"
-    (openpgp-fingerprint
-     "CABB A931 C0FF EEC6 900D  0CFB 090B 1199 3D9A EBB5"))))
-@end lisp
+@example
+guix time-machine @var{options}@dots{} -- @var{command} @var {arg}@dots{}
+@end example
 
-The specification above shows the name and URL of the channel.  The call
-to @code{make-channel-introduction} above specifies that authentication
-of this channel starts at commit @code{6f0d8cc@dots{}}, which is signed
-by the OpenPGP key with fingerprint @code{CABB A931@dots{}}.
+where @var{command} and @var{arg}@dots{} are passed unmodified to the
+@command{guix} command of the specified revision.  The @var{options} that define
+this revision are the same as for @command{guix pull} (@pxref{Invoking guix pull}):
 
-For the main channel, called @code{guix}, you automatically get that
-information from your Guix installation.  For other channels, include
-the channel introduction provided by the channel authors in your
-@file{channels.scm} file.  Make sure you retrieve the channel
-introduction from a trusted source since that is the root of your trust.
+@table @code
+@item --url=@var{url}
+@itemx --commit=@var{commit}
+@itemx --branch=@var{branch}
+Use the @code{guix} channel from the specified @var{url}, at the
+given @var{commit} (a valid Git commit ID represented as a hexadecimal
+string), or @var{branch}.
 
-If you're curious about the authentication mechanics, read on!
+@item --channels=@var{file}
+@itemx -C @var{file}
+Read the list of channels from @var{file}.  @var{file} must contain
+Scheme code that evaluates to a list of channel objects.
+@xref{Channels} for more information.
+@end table
 
-@subsection Using a Custom Guix Channel
+As for @command{guix pull}, the absence of any options means that the
+the latest commit on the master branch will be used. The command
 
-The channel called @code{guix} specifies where Guix itself---its command-line
-tools as well as its package collection---should be downloaded.  For instance,
-suppose you want to update from your own copy of the Guix repository at
-@code{example.org}, and specifically the @code{super-hacks} branch, you can
-write in @code{~/.config/guix/channels.scm} this specification:
+@example
+guix time-machine -- build hello
+@end example
 
-@lisp
-;; Tell 'guix pull' to use my own repo.
-(list (channel
-        (name 'guix)
-        (url "https://example.org/my-guix.git")
-        (branch "super-hacks")))
-@end lisp
+will thus build the package @code{hello} as defined in the master branch,
+which is in general a newer revision of Guix than you have installed.
+Time travel works in both directions!
 
-@noindent
-From there on, @command{guix pull} will fetch code from the @code{super-hacks}
-branch of the repository at @code{example.org}.
+Note that @command{guix time-machine} can trigger builds of channels and
+their dependencies, and these are controlled by the standard build
+options (@pxref{Common Build Options}).
 
-@subsection Specifying Additional Channels
+@node Inferiors
+@section Inferiors
 
-@cindex extending the package collection (channels)
-@cindex personal packages (channels)
-@cindex channels, for personal packages
-You can also specify @emph{additional channels} to pull from.  Let's say you
-have a bunch of custom package variants or personal packages that you think
-would make little sense to contribute to the Guix project, but would like to
-have these packages transparently available to you at the command line.  You
-would first write modules containing those package definitions (@pxref{Package
-Modules}), maintain them in a Git repository, and then you and anyone else can
-use it as an additional channel to get packages from.  Neat, no?
+@c TODO: Remove this once we're more confident about API stability.
+@quotation Note
+The functionality described here is a ``technology preview'' as of version
+@value{VERSION}.  As such, the interface is subject to change.
+@end quotation
 
-@c What follows stems from discussions at
-@c <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22629#134> as well as
-@c earlier discussions on guix-devel@gnu.org.
-@quotation Warning
-Before you, dear user, shout---``woow this is @emph{soooo coool}!''---and
-publish your personal channel to the world, we would like to share a few words
-of caution:
+@cindex inferiors
+@cindex composition of Guix revisions
+Sometimes you might need to mix packages from the revision of Guix you're
+currently running with packages available in a different revision of Guix.
+Guix @dfn{inferiors} allow you to achieve that by composing different Guix
+revisions in arbitrary ways.
 
-@itemize
-@item
-Before publishing a channel, please consider contributing your package
-definitions to Guix proper (@pxref{Contributing}).  Guix as a project is open
-to free software of all sorts, and packages in Guix proper are readily
-available to all Guix users and benefit from the project's quality assurance
-process.
+@cindex inferior packages
+Technically, an ``inferior'' is essentially a separate Guix process connected
+to your main Guix process through a REPL (@pxref{Invoking guix repl}).  The
+@code{(guix inferior)} module allows you to create inferiors and to
+communicate with them.  It also provides a high-level interface to browse and
+manipulate the packages that an inferior provides---@dfn{inferior packages}.
 
-@item
-When you maintain package definitions outside Guix, we, Guix developers,
-consider that @emph{the compatibility burden is on you}.  Remember that
-package modules and package definitions are just Scheme code that uses various
-programming interfaces (APIs).  We want to remain free to change these APIs to
-keep improving Guix, possibly in ways that break your channel.  We never
-change APIs gratuitously, but we will @emph{not} commit to freezing APIs
-either.
+When combined with channels (@pxref{Channels}), inferiors provide a simple way
+to interact with a separate revision of Guix.  For example, let's assume you
+want to install in your profile the current @code{guile} package, along with
+the @code{guile-json} as it existed in an older revision of Guix---perhaps
+because the newer @code{guile-json} has an incompatible API and you want to
+run your code against the old API@.  To do that, you could write a manifest for
+use by @code{guix package --manifest} (@pxref{Invoking guix package}); in that
+manifest, you would create an inferior for that old Guix revision you care
+about, and you would look up the @code{guile-json} package in the inferior:
 
-@item
-Corollary: if you're using an external channel and that channel breaks, please
-@emph{report the issue to the channel authors}, not to the Guix project.
-@end itemize
+@lisp
+(use-modules (guix inferior) (guix channels)
+             (srfi srfi-1))   ;for 'first'
 
-You've been warned!  Having said this, we believe external channels are a
-practical way to exert your freedom to augment Guix' package collection and to
-share your improvements, which are basic tenets of
-@uref{https://www.gnu.org/philosophy/free-sw.html, free software}.  Please
-email us at @email{guix-devel@@gnu.org} if you'd like to discuss this.
-@end quotation
+(define channels
+  ;; This is the old revision from which we want to
+  ;; extract guile-json.
+  (list (channel
+         (name 'guix)
+         (url "https://git.savannah.gnu.org/git/guix.git")
+         (commit
+          "65956ad3526ba09e1f7a40722c96c6ef7c0936fe"))))
 
-To use a channel, write @code{~/.config/guix/channels.scm} to instruct
-@command{guix pull} to pull from it @emph{in addition} to the default Guix
-channel(s):
+(define inferior
+  ;; An inferior representing the above revision.
+  (inferior-for-channels channels))
 
-@vindex %default-channels
-@lisp
-;; Add my personal packages to those Guix provides.
-(cons (channel
-        (name 'my-personal-packages)
-        (url "https://example.org/personal-packages.git"))
-      %default-channels)
+;; Now create a manifest with the current "guile" package
+;; and the old "guile-json" package.
+(packages->manifest
+ (list (first (lookup-inferior-packages inferior "guile-json"))
+       (specification->package "guile")))
 @end lisp
 
-@noindent
-Note that the snippet above is (as always!)@: Scheme code; we use @code{cons} to
-add a channel the list of channels that the variable @code{%default-channels}
-is bound to (@pxref{Pairs, @code{cons} and lists,, guile, GNU Guile Reference
-Manual}).  With this file in place, @command{guix pull} builds not only Guix
-but also the package modules from your own repository.  The result in
-@file{~/.config/guix/current} is the union of Guix with your own package
-modules:
+On its first run, @command{guix package --manifest} might have to build the
+channel you specified before it can create the inferior; subsequent runs will
+be much faster because the Guix revision will be cached.
 
-@example
-$ guix pull --list-generations
-@dots{}
-Generation 19	Aug 27 2018 16:20:48
-  guix d894ab8
-    repository URL: https://git.savannah.gnu.org/git/guix.git
-    branch: master
-    commit: d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300
-  my-personal-packages dd3df5e
-    repository URL: https://example.org/personal-packages.git
-    branch: master
-    commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb
-  11 new packages: my-gimp, my-emacs-with-cool-features, @dots{}
-  4 packages upgraded: emacs-racket-mode@@0.0.2-2.1b78827, @dots{}
-@end example
+The @code{(guix inferior)} module provides the following procedures to open an
+inferior:
 
-@noindent
-The output of @command{guix pull} above shows that Generation@tie{}19 includes
-both Guix and packages from the @code{my-personal-packages} channel.  Among
-the new and upgraded packages that are listed, some like @code{my-gimp} and
-@code{my-emacs-with-cool-features} might come from
-@code{my-personal-packages}, while others come from the Guix default channel.
+@deffn {Scheme Procedure} inferior-for-channels @var{channels} @
+   [#:cache-directory] [#:ttl]
+Return an inferior for @var{channels}, a list of channels.  Use the cache at
+@var{cache-directory}, where entries can be reclaimed after @var{ttl} seconds.
+This procedure opens a new connection to the build daemon.
 
-To create a channel, create a Git repository containing your own package
-modules and make it available.  The repository can contain anything, but a
-useful channel will contain Guile modules that export packages.  Once you
-start using a channel, Guix will behave as if the root directory of that
-channel's Git repository has been added to the Guile load path (@pxref{Load
-Paths,,, guile, GNU Guile Reference Manual}).  For example, if your channel
-contains a file at @file{my-packages/my-tools.scm} that defines a Guile
-module, then the module will be available under the name @code{(my-packages
-my-tools)}, and you will be able to use it like any other module
-(@pxref{Modules,,, guile, GNU Guile Reference Manual}).
+As a side effect, this procedure may build or substitute binaries for
+@var{channels}, which can take time.
+@end deffn
 
-@cindex dependencies, channels
-@cindex meta-data, channels
-@subsection Declaring Channel Dependencies
+@deffn {Scheme Procedure} open-inferior @var{directory} @
+  [#:command "bin/guix"]
+Open the inferior Guix in @var{directory}, running
+@code{@var{directory}/@var{command} repl} or equivalent.  Return @code{#f} if
+the inferior could not be launched.
+@end deffn
 
-Channel authors may decide to augment a package collection provided by other
-channels.  They can declare their channel to be dependent on other channels in
-a meta-data file @file{.guix-channel}, which is to be placed in the root of
-the channel repository.
+@cindex inferior packages
+The procedures listed below allow you to obtain and manipulate inferior
+packages.
 
-The meta-data file should contain a simple S-expression like this:
+@deffn {Scheme Procedure} inferior-packages @var{inferior}
+Return the list of packages known to @var{inferior}.
+@end deffn
 
-@lisp
-(channel
- (version 0)
- (dependencies
-  (channel
-   (name some-collection)
-   (url "https://example.org/first-collection.git")
-
-   ;; The 'introduction' bit below is optional: you would
-   ;; provide it for dependencies that can be authenticated.
-   (introduction
-    (channel-introduction
-      (version 0)
-      (commit "a8883b58dc82e167c96506cf05095f37c2c2c6cd")
-      (signer "CABB A931 C0FF EEC6 900D  0CFB 090B 1199 3D9A EBB5"))))
-  (channel
-   (name some-other-collection)
-   (url "https://example.org/second-collection.git")
-   (branch "testing"))))
-@end lisp
+@deffn {Scheme Procedure} lookup-inferior-packages @var{inferior} @var{name} @
+   [@var{version}]
+Return the sorted list of inferior packages matching @var{name} in
+@var{inferior}, with highest version numbers first.  If @var{version} is true,
+return only packages with a version number prefixed by @var{version}.
+@end deffn
 
-In the above example this channel is declared to depend on two other channels,
-which will both be fetched automatically.  The modules provided by the channel
-will be compiled in an environment where the modules of all these declared
-channels are available.
+@deffn {Scheme Procedure} inferior-package? @var{obj}
+Return true if @var{obj} is an inferior package.
+@end deffn
 
-For the sake of reliability and maintainability, you should avoid dependencies
-on channels that you don't control, and you should aim to keep the number of
-dependencies to a minimum.
+@deffn {Scheme Procedure} inferior-package-name @var{package}
+@deffnx {Scheme Procedure} inferior-package-version @var{package}
+@deffnx {Scheme Procedure} inferior-package-synopsis @var{package}
+@deffnx {Scheme Procedure} inferior-package-description @var{package}
+@deffnx {Scheme Procedure} inferior-package-home-page @var{package}
+@deffnx {Scheme Procedure} inferior-package-location @var{package}
+@deffnx {Scheme Procedure} inferior-package-inputs @var{package}
+@deffnx {Scheme Procedure} inferior-package-native-inputs @var{package}
+@deffnx {Scheme Procedure} inferior-package-propagated-inputs @var{package}
+@deffnx {Scheme Procedure} inferior-package-transitive-propagated-inputs @var{package}
+@deffnx {Scheme Procedure} inferior-package-native-search-paths @var{package}
+@deffnx {Scheme Procedure} inferior-package-transitive-native-search-paths @var{package}
+@deffnx {Scheme Procedure} inferior-package-search-paths @var{package}
+These procedures are the counterpart of package record accessors
+(@pxref{package Reference}).  Most of them work by querying the inferior
+@var{package} comes from, so the inferior must still be live when you call
+these procedures.
+@end deffn
 
-@cindex subdirectory, channels
-@subsection Package Modules in a Sub-directory
+Inferior packages can be used transparently like any other package or
+file-like object in G-expressions (@pxref{G-Expressions}).  They are also
+transparently handled by the @code{packages->manifest} procedure, which is
+commonly use in manifests (@pxref{Invoking guix package, the
+@option{--manifest} option of @command{guix package}}).  Thus you can insert
+an inferior package pretty much anywhere you would insert a regular package:
+in manifests, in the @code{packages} field of your @code{operating-system}
+declaration, and so on.
 
-As a channel author, you may want to keep your channel modules in a
-sub-directory.  If your modules are in the sub-directory @file{guix}, you must
-add a meta-data file @file{.guix-channel} that contains:
+@node Invoking guix describe
+@section Invoking @command{guix describe}
 
-@lisp
-(channel
-  (version 0)
-  (directory "guix"))
-@end lisp
+@cindex reproducibility
+@cindex replicating Guix
+Often you may want to answer questions like: ``Which revision of Guix am I
+using?'' or ``Which channels am I using?''  This is useful information in many
+situations: if you want to @emph{replicate} an environment on a different
+machine or user account, if you want to report a bug or to determine what
+change in the channels you are using caused it, or if you want to record your
+system state for reproducibility purposes.  The @command{guix describe}
+command answers these questions.
 
-@cindex channel authorizations
-@subsection Specifying Channel Authorizations
+When run from a @command{guix pull}ed @command{guix}, @command{guix describe}
+displays the channel(s) that it was built from, including their repository URL
+and commit IDs (@pxref{Channels}):
 
-@anchor{channel-authorizations}
-As we saw above, Guix ensures the source code it pulls from channels
-comes from authorized developers.  As a channel author, you need to
-specify the list of authorized developers in the
-@file{.guix-authorizations} file in the channel's Git repository.  The
-authentication rule is simple: each commit must be signed by a key
-listed in the @file{.guix-authorizations} file of its parent
-commit(s)@footnote{Git commits form a @dfn{directed acyclic graph}
-(DAG).  Each commit can have zero or more parents; ``regular'' commits
-have one parent and merge commits have two parent commits.  Read
-@uref{https://eagain.net/articles/git-for-computer-scientists/, @i{Git
-for Computer Scientists}} for a great overview.}  The
-@file{.guix-authorizations} file looks like this:
+@example
+$ guix describe
+Generation 10	Sep 03 2018 17:32:44	(current)
+  guix e0fa68c
+    repository URL: https://git.savannah.gnu.org/git/guix.git
+    branch: master
+    commit: e0fa68c7718fffd33d81af415279d6ddb518f727
+@end example
 
-@lisp
-;; Example '.guix-authorizations' file.
+If you're familiar with the Git version control system, this is similar in
+spirit to @command{git describe}; the output is also similar to that of
+@command{guix pull --list-generations}, but limited to the current generation
+(@pxref{Invoking guix pull, the @option{--list-generations} option}).  Because
+the Git commit ID shown above unambiguously refers to a snapshot of Guix, this
+information is all it takes to describe the revision of Guix you're using, and
+also to replicate it.
 
-(authorizations
- (version 0)               ;current file format version
+To make it easier to replicate Guix, @command{guix describe} can also be asked
+to return a list of channels instead of the human-readable description above:
 
- (("AD17 A21E F8AE D8F1 CC02  DBD9 F8AE D8F1 765C 61E3"
-   (name "alice"))
-  ("2A39 3FFF 68F4 EF7A 3D29  12AF 68F4 EF7A 22FB B2D5"
-   (name "bob"))
-  ("CABB A931 C0FF EEC6 900D  0CFB 090B 1199 3D9A EBB5"
-   (name "charlie"))))
-@end lisp
+@example
+$ guix describe -f channels
+(list (channel
+        (name 'guix)
+        (url "https://git.savannah.gnu.org/git/guix.git")
+        (commit
+          "e0fa68c7718fffd33d81af415279d6ddb518f727")
+        (introduction
+          (make-channel-introduction
+            "9edb3f66fd807b096b48283debdcddccfea34bad"
+            (openpgp-fingerprint
+              "BBB0 2DDF 2CEA F6A8 0D1D  E643 A2A0 6DF2 A33A 54FA")))))
+@end example
 
-Each fingerprint is followed by optional key/value pairs, as in the
-example above.  Currently these key/value pairs are ignored.
+@noindent
+You can save this to a file and feed it to @command{guix pull -C} on some
+other machine or at a later point in time, which will instantiate @emph{this
+exact Guix revision} (@pxref{Invoking guix pull, the @option{-C} option}).
+From there on, since you're able to deploy the same revision of Guix, you can
+just as well @emph{replicate a complete software environment}.  We humbly
+think that this is @emph{awesome}, and we hope you'll like it too!
 
-This authentication rule creates a chicken-and-egg issue: how do we
-authenticate the first commit?  Related to that: how do we deal with
-channels whose repository history contains unsigned commits and lack
-@file{.guix-authorizations}?  And how do we fork existing channels?
+The details of the options supported by @command{guix describe} are as
+follows:
 
-@cindex channel introduction
-Channel introductions answer these questions by describing the first
-commit of a channel that should be authenticated.  The first time a
-channel is fetched with @command{guix pull} or @command{guix
-time-machine}, the command looks up the introductory commit and verifies
-that it is signed by the specified OpenPGP key.  From then on, it
-authenticates commits according to the rule above.
+@table @code
+@item --format=@var{format}
+@itemx -f @var{format}
+Produce output in the specified @var{format}, one of:
 
-Additionally, your channel must provide all the OpenPGP keys that were
-ever mentioned in @file{.guix-authorizations}, stored as @file{.key}
-files, which can be either binary or ``ASCII-armored''.  By default,
-those @file{.key} files are searched for in the branch named
-@code{keyring} but you can specify a different branch name in
-@code{.guix-channel} like so:
+@table @code
+@item human
+produce human-readable output;
+@item channels
+produce a list of channel specifications that can be passed to @command{guix
+pull -C} or installed as @file{~/.config/guix/channels.scm} (@pxref{Invoking
+guix pull});
+@item channels-sans-intro
+like @code{channels}, but omit the @code{introduction} field; use it to
+produce a channel specification suitable for Guix version 1.1.0 or
+earlier---the @code{introduction} field has to do with channel
+authentication (@pxref{Channels, Channel Authentication}) and is not
+supported by these older versions;
+@item json
+@cindex JSON
+produce a list of channel specifications in JSON format;
+@item recutils
+produce a list of channel specifications in Recutils format.
+@end table
 
-@lisp
-(channel
-  (version 0)
-  (keyring-reference "my-keyring-branch"))
-@end lisp
+@item --list-formats
+Display available formats for @option{--format} option.
 
-To summarize, as the author of a channel, there are three things you have
-to do to allow users to authenticate your code:
+@item --profile=@var{profile}
+@itemx -p @var{profile}
+Display information about @var{profile}.
+@end table
 
-@enumerate
-@item
-Export the OpenPGP keys of past and present committers with @command{gpg
---export} and store them in @file{.key} files, by default in a branch
-named @code{keyring} (we recommend making it an @dfn{orphan branch}).
+@node Invoking guix archive
+@section Invoking @command{guix archive}
 
-@item
-Introduce an initial @file{.guix-authorizations} in the channel's
-repository.  Do that in a signed commit (@pxref{Commit Access}, for
-information on how to sign Git commits.)
+@cindex @command{guix archive}
+@cindex archive
+The @command{guix archive} command allows users to @dfn{export} files
+from the store into a single archive, and to later @dfn{import} them on
+a machine that runs Guix.
+In particular, it allows store files to be transferred from one machine
+to the store on another machine.
 
-@item
-Advertise the channel introduction, for instance on your channel's web
-page.  The channel introduction, as we saw above, is the commit/key
-pair---i.e., the commit that introduced @file{.guix-authorizations}, and
-the fingerprint of the OpenPGP used to sign it.
-@end enumerate
+@quotation Note
+If you're looking for a way to produce archives in a format suitable for
+tools other than Guix, @pxref{Invoking guix pack}.
+@end quotation
 
-Before pushing to your public Git repository, you can run @command{guix
-git-authenticate} to verify that you did sign all the commits you are
-about to push with an authorized key:
+@cindex exporting store items
+To export store files as an archive to standard output, run:
 
 @example
-guix git authenticate @var{commit} @var{signer}
+guix archive --export @var{options} @var{specifications}...
 @end example
 
-@noindent
-where @var{commit} and @var{signer} are your channel introduction.
-@xref{Invoking guix git authenticate}, for details.
+@var{specifications} may be either store file names or package
+specifications, as for @command{guix package} (@pxref{Invoking guix
+package}).  For instance, the following command creates an archive
+containing the @code{gui} output of the @code{git} package and the main
+output of @code{emacs}:
 
-Publishing a signed channel requires discipline: any mistake, such as an
-unsigned commit or a commit signed by an unauthorized key, will prevent
-users from pulling from your channel---well, that's the whole point of
-authentication!  Pay attention to merges in particular: merge commits
-are considered authentic if and only if they are signed by a key present
-in the @file{.guix-authorizations} file of @emph{both} branches.
+@example
+guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar
+@end example
 
-@cindex primary URL, channels
-@subsection Primary URL
+If the specified packages are not built yet, @command{guix archive}
+automatically builds them.  The build process may be controlled with the
+common build options (@pxref{Common Build Options}).
 
-Channel authors can indicate the primary URL of their channel's Git
-repository in the @file{.guix-channel} file, like so:
-
-@lisp
-(channel
-  (version 0)
-  (url "https://example.org/guix.git"))
-@end lisp
-
-This allows @command{guix pull} to determine whether it is pulling code
-from a mirror of the channel; when that is the case, it warns the user
-that the mirror might be stale and displays the primary URL.  That way,
-users cannot be tricked into fetching code from a stale mirror that does
-not receive security updates.
+To transfer the @code{emacs} package to a machine connected over SSH,
+one would run:
 
-This feature only makes sense for authenticated repositories, such as
-the official @code{guix} channel, for which @command{guix pull} ensures
-the code it fetches is authentic.
+@example
+guix archive --export -r emacs | ssh the-machine guix archive --import
+@end example
 
-@cindex news, for channels
-@subsection Writing Channel News
+@noindent
+Similarly, a complete user profile may be transferred from one machine
+to another like this:
 
-Channel authors may occasionally want to communicate to their users
-information about important changes in the channel.  You'd send them all
-an email, but that's not convenient.
+@example
+guix archive --export -r $(readlink -f ~/.guix-profile) | \
+  ssh the-machine guix archive --import
+@end example
 
-Instead, channels can provide a @dfn{news file}; when the channel users
-run @command{guix pull}, that news file is automatically read and
-@command{guix pull --news} can display the announcements that correspond
-to the new commits that have been pulled, if any.
+@noindent
+However, note that, in both examples, all of @code{emacs} and the
+profile as well as all of their dependencies are transferred (due to
+@option{-r}), regardless of what is already available in the store on
+the target machine.  The @option{--missing} option can help figure out
+which items are missing from the target store.  The @command{guix copy}
+command simplifies and optimizes this whole process, so this is probably
+what you should use in this case (@pxref{Invoking guix copy}).
 
-To do that, channel authors must first declare the name of the news file
-in their @file{.guix-channel} file:
+@cindex nar, archive format
+@cindex normalized archive (nar)
+@cindex nar bundle, archive format
+Each store item is written in the @dfn{normalized archive} or @dfn{nar}
+format (described below), and the output of @command{guix archive
+--export} (and input of @command{guix archive --import}) is a @dfn{nar
+bundle}.
 
-@lisp
-(channel
-  (version 0)
-  (news-file "etc/news.txt"))
-@end lisp
+The nar format is
+comparable in spirit to `tar', but with differences
+that make it more appropriate for our purposes.  First, rather than
+recording all Unix metadata for each file, the nar format only mentions
+the file type (regular, directory, or symbolic link); Unix permissions
+and owner/group are dismissed.  Second, the order in which directory
+entries are stored always follows the order of file names according to
+the C locale collation order.  This makes archive production fully
+deterministic.
 
-The news file itself, @file{etc/news.txt} in this example, must look
-something like this:
+That nar bundle format is essentially the concatenation of zero or more
+nars along with metadata for each store item it contains: its file name,
+references, corresponding derivation, and a digital signature.
 
-@lisp
-(channel-news
-  (version 0)
-  (entry (tag "the-bug-fix")
-         (title (en "Fixed terrible bug")
-                (fr "Oh la la"))
-         (body (en "@@emph@{Good news@}!  It's fixed!")
-               (eo "Certe ĝi pli bone funkcias nun!")))
-  (entry (commit "bdcabe815cd28144a2d2b4bc3c5057b051fa9906")
-         (title (en "Added a great package")
-                (ca "Què vol dir guix?"))
-         (body (en "Don't miss the @@code@{hello@} package!"))))
-@end lisp
+When exporting, the daemon digitally signs the contents of the archive,
+and that digital signature is appended.  When importing, the daemon
+verifies the signature and rejects the import in case of an invalid
+signature or if the signing key is not authorized.
+@c FIXME: Add xref to daemon doc about signatures.
 
-While the news file is using the Scheme syntax, avoid naming it with a
-@file{.scm} extension or else it will get picked up when building the
-channel and yield an error since it is not a valid module.
-Alternatively, you can move the channel module to a subdirectory and
-store the news file in another directory.
+The main options are:
 
-The file consists of a list of @dfn{news entries}.  Each entry is
-associated with a commit or tag: it describes changes made in this
-commit, possibly in preceding commits as well.  Users see entries only
-the first time they obtain the commit the entry refers to.
+@table @code
+@item --export
+Export the specified store files or packages (see below).  Write the
+resulting archive to the standard output.
 
-The @code{title} field should be a one-line summary while @code{body}
-can be arbitrarily long, and both can contain Texinfo markup
-(@pxref{Overview,,, texinfo, GNU Texinfo}).  Both the title and body are
-a list of language tag/message tuples, which allows @command{guix pull}
-to display news in the language that corresponds to the user's locale.
+Dependencies are @emph{not} included in the output, unless
+@option{--recursive} is passed.
 
-If you want to translate news using a gettext-based workflow, you can
-extract translatable strings with @command{xgettext} (@pxref{xgettext
-Invocation,,, gettext, GNU Gettext Utilities}).  For example, assuming
-you write news entries in English first, the command below creates a PO
-file containing the strings to translate:
+@item -r
+@itemx --recursive
+When combined with @option{--export}, this instructs @command{guix archive}
+to include dependencies of the given items in the archive.  Thus, the
+resulting archive is self-contained: it contains the closure of the
+exported store items.
 
-@example
-xgettext -o news.po -l scheme -ken etc/news.txt
-@end example
+@item --import
+Read an archive from the standard input, and import the files listed
+therein into the store.  Abort if the archive has an invalid digital
+signature, or if it is signed by a public key not among the authorized
+keys (see @option{--authorize} below).
 
-To sum up, yes, you could use your channel as a blog.  But beware, this
-is @emph{not quite} what your users might expect.
+@item --missing
+Read a list of store file names from the standard input, one per line,
+and write on the standard output the subset of these files missing from
+the store.
 
-@subsection Replicating Guix
+@item --generate-key[=@var{parameters}]
+@cindex signing, archives
+Generate a new key pair for the daemon.  This is a prerequisite before
+archives can be exported with @option{--export}.  Note that this
+operation usually takes time, because it needs to gather enough entropy
+to generate the key pair.
 
-@cindex pinning, channels
-@cindex replicating Guix
-@cindex reproducibility, of Guix
-The @command{guix pull --list-generations} output above shows precisely which
-commits were used to build this instance of Guix.  We can thus replicate it,
-say, on another machine, by providing a channel specification in
-@file{~/.config/guix/channels.scm} that is ``pinned'' to these commits:
+The generated key pair is typically stored under @file{/etc/guix}, in
+@file{signing-key.pub} (public key) and @file{signing-key.sec} (private
+key, which must be kept secret).  When @var{parameters} is omitted,
+an ECDSA key using the Ed25519 curve is generated, or, for Libgcrypt
+versions before 1.6.0, it is a 4096-bit RSA key.
+Alternatively, @var{parameters} can specify
+@code{genkey} parameters suitable for Libgcrypt (@pxref{General
+public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The
+Libgcrypt Reference Manual}).
 
-@lisp
-;; Deploy specific commits of my channels of interest.
-(list (channel
-       (name 'guix)
-       (url "https://git.savannah.gnu.org/git/guix.git")
-       (commit "6298c3ffd9654d3231a6f25390b056483e8f407c"))
-      (channel
-       (name 'my-personal-packages)
-       (url "https://example.org/personal-packages.git")
-       (commit "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb")))
-@end lisp
+@item --authorize
+@cindex authorizing, archives
+Authorize imports signed by the public key passed on standard input.
+The public key must be in ``s-expression advanced format''---i.e., the
+same format as the @file{signing-key.pub} file.
 
-The @command{guix describe --format=channels} command can even generate this
-list of channels directly (@pxref{Invoking guix describe}).  The resulting
-file can be used with the -C options of @command{guix pull}
-(@pxref{Invoking guix pull}) or @command{guix time-machine}
-(@pxref{Invoking guix time-machine}).
+The list of authorized keys is kept in the human-editable file
+@file{/etc/guix/acl}.  The file contains
+@url{https://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
+s-expressions''} and is structured as an access-control list in the
+@url{https://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
+(SPKI)}.
 
-At this point the two machines run the @emph{exact same Guix}, with access to
-the @emph{exact same packages}.  The output of @command{guix build gimp} on
-one machine will be exactly the same, bit for bit, as the output of the same
-command on the other machine.  It also means both machines have access to all
-the source code of Guix and, transitively, to all the source code of every
-package it defines.
+@item --extract=@var{directory}
+@itemx -x @var{directory}
+Read a single-item archive as served by substitute servers
+(@pxref{Substitutes}) and extract it to @var{directory}.  This is a
+low-level operation needed in only very narrow use cases; see below.
 
-This gives you super powers, allowing you to track the provenance of binary
-artifacts with very fine grain, and to reproduce software environments at
-will---some sort of ``meta reproducibility'' capabilities, if you will.
-@xref{Inferiors}, for another way to take advantage of these super powers.
+For example, the following command extracts the substitute for Emacs
+served by @code{@value{SUBSTITUTE-SERVER}} to @file{/tmp/emacs}:
 
-@node Invoking guix time-machine
-@section Invoking @command{guix time-machine}
+@example
+$ wget -O - \
+  https://@value{SUBSTITUTE-SERVER}/nar/gzip/@dots{}-emacs-24.5 \
+  | gunzip | guix archive -x /tmp/emacs
+@end example
 
-@cindex @command{guix time-machine}
-@cindex pinning, channels
-@cindex replicating Guix
-@cindex reproducibility, of Guix
+Single-item archives are different from multiple-item archives produced
+by @command{guix archive --export}; they contain a single store item,
+and they do @emph{not} embed a signature.  Thus this operation does
+@emph{no} signature verification and its output should be considered
+unsafe.
 
-The @command{guix time-machine} command provides access to other
-revisions of Guix, for example to install older versions of packages,
-or to reproduce a computation in an identical environment.  The revision
-of Guix to be used is defined by a commit or by a channel
-description file created by @command{guix describe}
-(@pxref{Invoking guix describe}).
+The primary purpose of this operation is to facilitate inspection of
+archive contents coming from possibly untrusted substitute servers
+(@pxref{Invoking guix challenge}).
 
-The general syntax is:
+@item --list
+@itemx -t
+Read a single-item archive as served by substitute servers
+(@pxref{Substitutes}) and print the list of files it contains, as in
+this example:
 
 @example
-guix time-machine @var{options}@dots{} -- @var{command} @var {arg}@dots{}
+$ wget -O - \
+  https://@value{SUBSTITUTE-SERVER}/nar/lzip/@dots{}-emacs-26.3 \
+  | lzip -d | guix archive -t
 @end example
 
-where @var{command} and @var{arg}@dots{} are passed unmodified to the
-@command{guix} command of the specified revision.  The @var{options} that define
-this revision are the same as for @command{guix pull} (@pxref{Invoking guix pull}):
-
-@table @code
-@item --url=@var{url}
-@itemx --commit=@var{commit}
-@itemx --branch=@var{branch}
-Use the @code{guix} channel from the specified @var{url}, at the
-given @var{commit} (a valid Git commit ID represented as a hexadecimal
-string), or @var{branch}.
-
-@item --channels=@var{file}
-@itemx -C @var{file}
-Read the list of channels from @var{file}.  @var{file} must contain
-Scheme code that evaluates to a list of channel objects.
-@xref{Channels} for more information.
 @end table
 
-As for @command{guix pull}, the absence of any options means that the
-the latest commit on the master branch will be used. The command
+@c *********************************************************************
+@node Channels
+@chapter Channels
+
+@cindex channels
+@cindex @file{channels.scm}, configuration file
+@cindex configuration file for channels
+@cindex @command{guix pull}, configuration file
+@cindex configuration of @command{guix pull}
+Guix and its package collection are updated by running @command{guix pull}
+(@pxref{Invoking guix pull}).  By default @command{guix pull} downloads and
+deploys Guix itself from the official GNU@tie{}Guix repository.  This can be
+customized by defining @dfn{channels} in the
+@file{~/.config/guix/channels.scm} file.  A channel specifies a URL and branch
+of a Git repository to be deployed, and @command{guix pull} can be instructed
+to pull from one or more channels.  In other words, channels can be used
+to @emph{customize} and to @emph{extend} Guix, as we will see below.
+Guix is able to take into account security concerns and deal with authenticated
+updates.
+
+@menu
+* Specifying Additional Channels::  Extending the package collection.
+* Using a Custom Guix Channel::  Using a customized Guix.
+* Replicating Guix::            Running the @emph{exact same} Guix.
+* Channel Authentication::      How Guix verifies what it fetches.
+* Primary URL::                 Distinguishing mirror to original.
+* Creating a Channel::          How to write your custom channel.
+* Package Modules in a Sub-directory::  Specifying the channel's package modules location.
+* Declaring Channel Dependencies::  How to depend on other channels.
+* Specifying Channel Authorizations::  Defining channel authors authorizations.
+* Writing Channel News::        Communicating information to channel's users.
+@end menu
+
+@node Specifying Additional Channels
+@section Specifying Additional Channels
+
+@cindex extending the package collection (channels)
+@cindex variant packages (channels)
+You can specify @emph{additional channels} to pull from. To use a channel, write
+@code{~/.config/guix/channels.scm} to instruct @command{guix pull} to pull from it
+@emph{in addition} to the default Guix channel(s):
+
+@vindex %default-channels
+@lisp
+;; Add variant packages to those Guix provides.
+(cons (channel
+        (name 'variant-packages)
+        (url "https://example.org/variant-packages.git"))
+      %default-channels)
+@end lisp
+
+@noindent
+Note that the snippet above is (as always!)@: Scheme code; we use @code{cons} to
+add a channel the list of channels that the variable @code{%default-channels}
+is bound to (@pxref{Pairs, @code{cons} and lists,, guile, GNU Guile Reference
+Manual}).  With this file in place, @command{guix pull} builds not only Guix
+but also the package modules from your own repository.  The result in
+@file{~/.config/guix/current} is the union of Guix with your own package
+modules:
 
 @example
-guix time-machine -- build hello
+$ guix pull --list-generations
+@dots{}
+Generation 19	Aug 27 2018 16:20:48
+  guix d894ab8
+    repository URL: https://git.savannah.gnu.org/git/guix.git
+    branch: master
+    commit: d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300
+  variant-packages dd3df5e
+    repository URL: https://example.org/variant-packages.git
+    branch: master
+    commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb
+  11 new packages: variant-gimp, variant-emacs-with-cool-features, @dots{}
+  4 packages upgraded: emacs-racket-mode@@0.0.2-2.1b78827, @dots{}
 @end example
 
-will thus build the package @code{hello} as defined in the master branch,
-which is in general a newer revision of Guix than you have installed.
-Time travel works in both directions!
+@noindent
+The output of @command{guix pull} above shows that Generation@tie{}19 includes
+both Guix and packages from the @code{variant-personal-packages} channel.  Among
+the new and upgraded packages that are listed, some like @code{variant-gimp} and
+@code{variant-emacs-with-cool-features} might come from
+@code{variant-packages}, while others come from the Guix default channel.
 
-Note that @command{guix time-machine} can trigger builds of channels and
-their dependencies, and these are controlled by the standard build
-options (@pxref{Common Build Options}).
+@node Using a Custom Guix Channel
+@section Using a Custom Guix Channel
 
-@node Inferiors
-@section Inferiors
+The channel called @code{guix} specifies where Guix itself---its command-line
+tools as well as its package collection---should be downloaded.  For instance,
+suppose you want to update from another copy of the Guix repository at
+@code{example.org}, and specifically the @code{super-hacks} branch, you can
+write in @code{~/.config/guix/channels.scm} this specification:
 
-@c TODO: Remove this once we're more confident about API stability.
-@quotation Note
-The functionality described here is a ``technology preview'' as of version
-@value{VERSION}.  As such, the interface is subject to change.
-@end quotation
+@lisp
+;; Tell 'guix pull' to use another repo.
+(list (channel
+        (name 'guix)
+        (url "https://example.org/another-guix.git")
+        (branch "super-hacks")))
+@end lisp
 
-@cindex inferiors
-@cindex composition of Guix revisions
-Sometimes you might need to mix packages from the revision of Guix you're
-currently running with packages available in a different revision of Guix.
-Guix @dfn{inferiors} allow you to achieve that by composing different Guix
-revisions in arbitrary ways.
+@noindent
+From there on, @command{guix pull} will fetch code from the @code{super-hacks}
+branch of the repository at @code{example.org}.  The authentication concern is
+addressed below ((@pxref{Channel  Authentication}).
 
-@cindex inferior packages
-Technically, an ``inferior'' is essentially a separate Guix process connected
-to your main Guix process through a REPL (@pxref{Invoking guix repl}).  The
-@code{(guix inferior)} module allows you to create inferiors and to
-communicate with them.  It also provides a high-level interface to browse and
-manipulate the packages that an inferior provides---@dfn{inferior packages}.
+@node Replicating Guix
+@section Replicating Guix
 
-When combined with channels (@pxref{Channels}), inferiors provide a simple way
-to interact with a separate revision of Guix.  For example, let's assume you
-want to install in your profile the current @code{guile} package, along with
-the @code{guile-json} as it existed in an older revision of Guix---perhaps
-because the newer @code{guile-json} has an incompatible API and you want to
-run your code against the old API@.  To do that, you could write a manifest for
-use by @code{guix package --manifest} (@pxref{Invoking guix package}); in that
-manifest, you would create an inferior for that old Guix revision you care
-about, and you would look up the @code{guile-json} package in the inferior:
+@cindex pinning, channels
+@cindex replicating Guix
+@cindex reproducibility, of Guix
+The @command{guix pull --list-generations} output above shows precisely which
+commits were used to build this instance of Guix.  We can thus replicate it,
+say, on another machine, by providing a channel specification in
+@file{~/.config/guix/channels.scm} that is ``pinned'' to these commits:
 
 @lisp
-(use-modules (guix inferior) (guix channels)
-             (srfi srfi-1))   ;for 'first'
+;; Deploy specific commits of my channels of interest.
+(list (channel
+       (name 'guix)
+       (url "https://git.savannah.gnu.org/git/guix.git")
+       (commit "6298c3ffd9654d3231a6f25390b056483e8f407c"))
+      (channel
+       (name 'variant-packages)
+       (url "https://example.org/variant-packages.git")
+       (commit "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb")))
+@end lisp
 
-(define channels
-  ;; This is the old revision from which we want to
-  ;; extract guile-json.
-  (list (channel
-         (name 'guix)
-         (url "https://git.savannah.gnu.org/git/guix.git")
-         (commit
-          "65956ad3526ba09e1f7a40722c96c6ef7c0936fe"))))
+The @command{guix describe --format=channels} command can even generate this
+list of channels directly (@pxref{Invoking guix describe}).  The resulting
+file can be used with the -C options of @command{guix pull}
+(@pxref{Invoking guix pull}) or @command{guix time-machine}
+(@pxref{Invoking guix time-machine}).
 
-(define inferior
-  ;; An inferior representing the above revision.
-  (inferior-for-channels channels))
+At this point the two machines run the @emph{exact same Guix}, with access to
+the @emph{exact same packages}.  The output of @command{guix build gimp} on
+one machine will be exactly the same, bit for bit, as the output of the same
+command on the other machine.  It also means both machines have access to all
+the source code of Guix and, transitively, to all the source code of every
+package it defines.
 
-;; Now create a manifest with the current "guile" package
-;; and the old "guile-json" package.
-(packages->manifest
- (list (first (lookup-inferior-packages inferior "guile-json"))
-       (specification->package "guile")))
+This gives you super powers, allowing you to track the provenance of binary
+artifacts with very fine grain, and to reproduce software environments at
+will---some sort of ``meta reproducibility'' capabilities, if you will.
+@xref{Inferiors}, for another way to take advantage of these super powers.
+
+@node Channel Authentication
+@section Channel Authentication
+
+@anchor{channel-authentication}
+@cindex authentication, of channel code
+The @command{guix pull} and @command{guix time-machine} commands
+@dfn{authenticate} the code retrieved from channels: they make sure each
+commit that is fetched is signed by an authorized developer.  The goal
+is to protect from unauthorized modifications to the channel that would
+lead users to run malicious code.
+
+As a user, you must provide a @dfn{channel introduction} in your
+channels file so that Guix knows how to authenticate its first commit.
+A channel specification, including its introduction, looks something
+along these lines:
+
+@lisp
+(channel
+  (name 'some-channel)
+  (url "https://example.org/some-channel.git")
+  (introduction
+   (make-channel-introduction
+    "6f0d8cc0d88abb59c324b2990bfee2876016bb86"
+    (openpgp-fingerprint
+     "CABB A931 C0FF EEC6 900D  0CFB 090B 1199 3D9A EBB5"))))
 @end lisp
 
-On its first run, @command{guix package --manifest} might have to build the
-channel you specified before it can create the inferior; subsequent runs will
-be much faster because the Guix revision will be cached.
+The specification above shows the name and URL of the channel.  The call
+to @code{make-channel-introduction} above specifies that authentication
+of this channel starts at commit @code{6f0d8cc@dots{}}, which is signed
+by the OpenPGP key with fingerprint @code{CABB A931@dots{}}.
 
-The @code{(guix inferior)} module provides the following procedures to open an
-inferior:
+For the main channel, called @code{guix}, you automatically get that
+information from your Guix installation.  For other channels, include
+the channel introduction provided by the channel authors in your
+@file{channels.scm} file.  Make sure you retrieve the channel
+introduction from a trusted source since that is the root of your trust.
 
-@deffn {Scheme Procedure} inferior-for-channels @var{channels} @
-   [#:cache-directory] [#:ttl]
-Return an inferior for @var{channels}, a list of channels.  Use the cache at
-@var{cache-directory}, where entries can be reclaimed after @var{ttl} seconds.
-This procedure opens a new connection to the build daemon.
+If you're curious about the authentication mechanics, read on!
 
-As a side effect, this procedure may build or substitute binaries for
-@var{channels}, which can take time.
-@end deffn
+@cindex primary URL, channels
+@node Primary URL
+@section Primary URL
 
-@deffn {Scheme Procedure} open-inferior @var{directory} @
-  [#:command "bin/guix"]
-Open the inferior Guix in @var{directory}, running
-@code{@var{directory}/@var{command} repl} or equivalent.  Return @code{#f} if
-the inferior could not be launched.
-@end deffn
+Channel authors can indicate the primary URL of their channel's Git
+repository in the @file{.guix-channel} file, like so:
 
-@cindex inferior packages
-The procedures listed below allow you to obtain and manipulate inferior
-packages.
+@lisp
+(channel
+  (version 0)
+  (url "https://example.org/guix.git"))
+@end lisp
 
-@deffn {Scheme Procedure} inferior-packages @var{inferior}
-Return the list of packages known to @var{inferior}.
-@end deffn
+This allows @command{guix pull} to determine whether it is pulling code
+from a mirror of the channel; when that is the case, it warns the user
+that the mirror might be stale and displays the primary URL.  That way,
+users cannot be tricked into fetching code from a stale mirror that does
+not receive security updates.
 
-@deffn {Scheme Procedure} lookup-inferior-packages @var{inferior} @var{name} @
-   [@var{version}]
-Return the sorted list of inferior packages matching @var{name} in
-@var{inferior}, with highest version numbers first.  If @var{version} is true,
-return only packages with a version number prefixed by @var{version}.
-@end deffn
+This feature only makes sense for authenticated repositories, such as
+the official @code{guix} channel, for which @command{guix pull} ensures
+the code it fetches is authentic.
 
-@deffn {Scheme Procedure} inferior-package? @var{obj}
-Return true if @var{obj} is an inferior package.
-@end deffn
+@cindex personal packages (channels)
+@cindex channels, for personal packages
+@node Creating a Channel
+@section Creating a Channel
 
-@deffn {Scheme Procedure} inferior-package-name @var{package}
-@deffnx {Scheme Procedure} inferior-package-version @var{package}
-@deffnx {Scheme Procedure} inferior-package-synopsis @var{package}
-@deffnx {Scheme Procedure} inferior-package-description @var{package}
-@deffnx {Scheme Procedure} inferior-package-home-page @var{package}
-@deffnx {Scheme Procedure} inferior-package-location @var{package}
-@deffnx {Scheme Procedure} inferior-package-inputs @var{package}
-@deffnx {Scheme Procedure} inferior-package-native-inputs @var{package}
-@deffnx {Scheme Procedure} inferior-package-propagated-inputs @var{package}
-@deffnx {Scheme Procedure} inferior-package-transitive-propagated-inputs @var{package}
-@deffnx {Scheme Procedure} inferior-package-native-search-paths @var{package}
-@deffnx {Scheme Procedure} inferior-package-transitive-native-search-paths @var{package}
-@deffnx {Scheme Procedure} inferior-package-search-paths @var{package}
-These procedures are the counterpart of package record accessors
-(@pxref{package Reference}).  Most of them work by querying the inferior
-@var{package} comes from, so the inferior must still be live when you call
-these procedures.
-@end deffn
+Let's say you have a bunch of custom package variants or personal packages
+that you think would make little sense to contribute to the Guix project, but
+would like to have these packages transparently available to you at the
+command line.  You would first write modules containing those package
+definitions (@pxref{Package Modules}), maintain them in a Git repository, and
+then you and anyone else can use it as an additional channel to get packages
+from.  Neat, no?
 
-Inferior packages can be used transparently like any other package or
-file-like object in G-expressions (@pxref{G-Expressions}).  They are also
-transparently handled by the @code{packages->manifest} procedure, which is
-commonly use in manifests (@pxref{Invoking guix package, the
-@option{--manifest} option of @command{guix package}}).  Thus you can insert
-an inferior package pretty much anywhere you would insert a regular package:
-in manifests, in the @code{packages} field of your @code{operating-system}
-declaration, and so on.
+@c What follows stems from discussions at
+@c <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22629#134> as well as
+@c earlier discussions on guix-devel@gnu.org.
+@quotation Warning
+Before you, dear user, shout---``woow this is @emph{soooo coool}!''---and
+publish your personal channel to the world, we would like to share a few words
+of caution:
 
-@node Invoking guix describe
-@section Invoking @command{guix describe}
+@itemize
+@item
+Before publishing a channel, please consider contributing your package
+definitions to Guix proper (@pxref{Contributing}).  Guix as a project is open
+to free software of all sorts, and packages in Guix proper are readily
+available to all Guix users and benefit from the project's quality assurance
+process.
 
-@cindex reproducibility
-@cindex replicating Guix
-Often you may want to answer questions like: ``Which revision of Guix am I
-using?'' or ``Which channels am I using?''  This is useful information in many
-situations: if you want to @emph{replicate} an environment on a different
-machine or user account, if you want to report a bug or to determine what
-change in the channels you are using caused it, or if you want to record your
-system state for reproducibility purposes.  The @command{guix describe}
-command answers these questions.
+@item
+When you maintain package definitions outside Guix, we, Guix developers,
+consider that @emph{the compatibility burden is on you}.  Remember that
+package modules and package definitions are just Scheme code that uses various
+programming interfaces (APIs).  We want to remain free to change these APIs to
+keep improving Guix, possibly in ways that break your channel.  We never
+change APIs gratuitously, but we will @emph{not} commit to freezing APIs
+either.
 
-When run from a @command{guix pull}ed @command{guix}, @command{guix describe}
-displays the channel(s) that it was built from, including their repository URL
-and commit IDs (@pxref{Channels}):
+@item
+Corollary: if you're using an external channel and that channel breaks, please
+@emph{report the issue to the channel authors}, not to the Guix project.
+@end itemize
 
-@example
-$ guix describe
-Generation 10	Sep 03 2018 17:32:44	(current)
-  guix e0fa68c
-    repository URL: https://git.savannah.gnu.org/git/guix.git
-    branch: master
-    commit: e0fa68c7718fffd33d81af415279d6ddb518f727
-@end example
+You've been warned!  Having said this, we believe external channels are a
+practical way to exert your freedom to augment Guix' package collection and to
+share your improvements, which are basic tenets of
+@uref{https://www.gnu.org/philosophy/free-sw.html, free software}.  Please
+email us at @email{guix-devel@@gnu.org} if you'd like to discuss this.
+@end quotation
 
-If you're familiar with the Git version control system, this is similar in
-spirit to @command{git describe}; the output is also similar to that of
-@command{guix pull --list-generations}, but limited to the current generation
-(@pxref{Invoking guix pull, the @option{--list-generations} option}).  Because
-the Git commit ID shown above unambiguously refers to a snapshot of Guix, this
-information is all it takes to describe the revision of Guix you're using, and
-also to replicate it.
+To create a channel, create a Git repository containing your own package
+modules and make it available.  The repository can contain anything, but a
+useful channel will contain Guile modules that export packages.  Once you
+start using a channel, Guix will behave as if the root directory of that
+channel's Git repository has been added to the Guile load path (@pxref{Load
+Paths,,, guile, GNU Guile Reference Manual}).  For example, if your channel
+contains a file at @file{my-packages/my-tools.scm} that defines a Guile
+module, then the module will be available under the name @code{(my-packages
+my-tools)}, and you will be able to use it like any other module
+(@pxref{Modules,,, guile, GNU Guile Reference Manual}).
 
-To make it easier to replicate Guix, @command{guix describe} can also be asked
-to return a list of channels instead of the human-readable description above:
+As a channel author, consider bundling authentication material with your
+channel so that users can authenticate it.  @xref{Channel
+Authentication}, and @ref{Specifying Channel Authorizations}, for info
+on how to do it.
 
-@example
-$ guix describe -f channels
-(list (channel
-        (name 'guix)
-        (url "https://git.savannah.gnu.org/git/guix.git")
-        (commit
-          "e0fa68c7718fffd33d81af415279d6ddb518f727")
-        (introduction
-          (make-channel-introduction
-            "9edb3f66fd807b096b48283debdcddccfea34bad"
-            (openpgp-fingerprint
-              "BBB0 2DDF 2CEA F6A8 0D1D  E643 A2A0 6DF2 A33A 54FA")))))
-@end example
 
-@noindent
-You can save this to a file and feed it to @command{guix pull -C} on some
-other machine or at a later point in time, which will instantiate @emph{this
-exact Guix revision} (@pxref{Invoking guix pull, the @option{-C} option}).
-From there on, since you're able to deploy the same revision of Guix, you can
-just as well @emph{replicate a complete software environment}.  We humbly
-think that this is @emph{awesome}, and we hope you'll like it too!
+@cindex subdirectory, channels
+@node Package Modules in a Sub-directory
+@section Package Modules in a Sub-directory
 
-The details of the options supported by @command{guix describe} are as
-follows:
+As a channel author, you may want to keep your channel modules in a
+sub-directory.  If your modules are in the sub-directory @file{guix}, you must
+add a meta-data file @file{.guix-channel} that contains:
 
-@table @code
-@item --format=@var{format}
-@itemx -f @var{format}
-Produce output in the specified @var{format}, one of:
+@lisp
+(channel
+  (version 0)
+  (directory "guix"))
+@end lisp
 
-@table @code
-@item human
-produce human-readable output;
-@item channels
-produce a list of channel specifications that can be passed to @command{guix
-pull -C} or installed as @file{~/.config/guix/channels.scm} (@pxref{Invoking
-guix pull});
-@item channels-sans-intro
-like @code{channels}, but omit the @code{introduction} field; use it to
-produce a channel specification suitable for Guix version 1.1.0 or
-earlier---the @code{introduction} field has to do with channel
-authentication (@pxref{Channels, Channel Authentication}) and is not
-supported by these older versions;
-@item json
-@cindex JSON
-produce a list of channel specifications in JSON format;
-@item recutils
-produce a list of channel specifications in Recutils format.
-@end table
+@cindex dependencies, channels
+@cindex meta-data, channels
+@node Declaring Channel Dependencies
+@section Declaring Channel Dependencies
 
-@item --list-formats
-Display available formats for @option{--format} option.
+Channel authors may decide to augment a package collection provided by other
+channels.  They can declare their channel to be dependent on other channels in
+a meta-data file @file{.guix-channel}, which is to be placed in the root of
+the channel repository.
 
-@item --profile=@var{profile}
-@itemx -p @var{profile}
-Display information about @var{profile}.
-@end table
+The meta-data file should contain a simple S-expression like this:
 
-@node Invoking guix archive
-@section Invoking @command{guix archive}
+@lisp
+(channel
+ (version 0)
+ (dependencies
+  (channel
+   (name 'some-collection)
+   (url "https://example.org/first-collection.git")
 
-@cindex @command{guix archive}
-@cindex archive
-The @command{guix archive} command allows users to @dfn{export} files
-from the store into a single archive, and to later @dfn{import} them on
-a machine that runs Guix.
-In particular, it allows store files to be transferred from one machine
-to the store on another machine.
+   ;; The 'introduction' bit below is optional: you would
+   ;; provide it for dependencies that can be authenticated.
+   (introduction
+    (channel-introduction
+      (version 0)
+      (commit "a8883b58dc82e167c96506cf05095f37c2c2c6cd")
+      (signer "CABB A931 C0FF EEC6 900D  0CFB 090B 1199 3D9A EBB5"))))
+  (channel
+   (name 'some-other-collection)
+   (url "https://example.org/second-collection.git")
+   (branch "testing"))))
+@end lisp
 
-@quotation Note
-If you're looking for a way to produce archives in a format suitable for
-tools other than Guix, @pxref{Invoking guix pack}.
-@end quotation
+In the above example this channel is declared to depend on two other channels,
+which will both be fetched automatically.  The modules provided by the channel
+will be compiled in an environment where the modules of all these declared
+channels are available.
 
-@cindex exporting store items
-To export store files as an archive to standard output, run:
+For the sake of reliability and maintainability, you should avoid dependencies
+on channels that you don't control, and you should aim to keep the number of
+dependencies to a minimum.
 
-@example
-guix archive --export @var{options} @var{specifications}...
-@end example
+@cindex channel authorizations
+@node Specifying Channel Authorizations
+@section Specifying Channel Authorizations
 
-@var{specifications} may be either store file names or package
-specifications, as for @command{guix package} (@pxref{Invoking guix
-package}).  For instance, the following command creates an archive
-containing the @code{gui} output of the @code{git} package and the main
-output of @code{emacs}:
+@anchor{channel-authorizations}
+As we saw above, Guix ensures the source code it pulls from channels
+comes from authorized developers.  As a channel author, you need to
+specify the list of authorized developers in the
+@file{.guix-authorizations} file in the channel's Git repository.  The
+authentication rule is simple: each commit must be signed by a key
+listed in the @file{.guix-authorizations} file of its parent
+commit(s)@footnote{Git commits form a @dfn{directed acyclic graph}
+(DAG).  Each commit can have zero or more parents; ``regular'' commits
+have one parent and merge commits have two parent commits.  Read
+@uref{https://eagain.net/articles/git-for-computer-scientists/, @i{Git
+for Computer Scientists}} for a great overview.}  The
+@file{.guix-authorizations} file looks like this:
 
-@example
-guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar
-@end example
+@lisp
+;; Example '.guix-authorizations' file.
 
-If the specified packages are not built yet, @command{guix archive}
-automatically builds them.  The build process may be controlled with the
-common build options (@pxref{Common Build Options}).
+(authorizations
+ (version 0)               ;current file format version
 
-To transfer the @code{emacs} package to a machine connected over SSH,
-one would run:
+ (("AD17 A21E F8AE D8F1 CC02  DBD9 F8AE D8F1 765C 61E3"
+   (name "alice"))
+  ("2A39 3FFF 68F4 EF7A 3D29  12AF 68F4 EF7A 22FB B2D5"
+   (name "bob"))
+  ("CABB A931 C0FF EEC6 900D  0CFB 090B 1199 3D9A EBB5"
+   (name "charlie"))))
+@end lisp
 
-@example
-guix archive --export -r emacs | ssh the-machine guix archive --import
-@end example
+Each fingerprint is followed by optional key/value pairs, as in the
+example above.  Currently these key/value pairs are ignored.
 
-@noindent
-Similarly, a complete user profile may be transferred from one machine
-to another like this:
+This authentication rule creates a chicken-and-egg issue: how do we
+authenticate the first commit?  Related to that: how do we deal with
+channels whose repository history contains unsigned commits and lack
+@file{.guix-authorizations}?  And how do we fork existing channels?
 
-@example
-guix archive --export -r $(readlink -f ~/.guix-profile) | \
-  ssh the-machine guix archive --import
-@end example
+@cindex channel introduction
+Channel introductions answer these questions by describing the first
+commit of a channel that should be authenticated.  The first time a
+channel is fetched with @command{guix pull} or @command{guix
+time-machine}, the command looks up the introductory commit and verifies
+that it is signed by the specified OpenPGP key.  From then on, it
+authenticates commits according to the rule above.
 
-@noindent
-However, note that, in both examples, all of @code{emacs} and the
-profile as well as all of their dependencies are transferred (due to
-@option{-r}), regardless of what is already available in the store on
-the target machine.  The @option{--missing} option can help figure out
-which items are missing from the target store.  The @command{guix copy}
-command simplifies and optimizes this whole process, so this is probably
-what you should use in this case (@pxref{Invoking guix copy}).
+Additionally, your channel must provide all the OpenPGP keys that were
+ever mentioned in @file{.guix-authorizations}, stored as @file{.key}
+files, which can be either binary or ``ASCII-armored''.  By default,
+those @file{.key} files are searched for in the branch named
+@code{keyring} but you can specify a different branch name in
+@code{.guix-channel} like so:
 
-@cindex nar, archive format
-@cindex normalized archive (nar)
-@cindex nar bundle, archive format
-Each store item is written in the @dfn{normalized archive} or @dfn{nar}
-format (described below), and the output of @command{guix archive
---export} (and input of @command{guix archive --import}) is a @dfn{nar
-bundle}.
+@lisp
+(channel
+  (version 0)
+  (keyring-reference "my-keyring-branch"))
+@end lisp
 
-The nar format is
-comparable in spirit to `tar', but with differences
-that make it more appropriate for our purposes.  First, rather than
-recording all Unix metadata for each file, the nar format only mentions
-the file type (regular, directory, or symbolic link); Unix permissions
-and owner/group are dismissed.  Second, the order in which directory
-entries are stored always follows the order of file names according to
-the C locale collation order.  This makes archive production fully
-deterministic.
+To summarize, as the author of a channel, there are three things you have
+to do to allow users to authenticate your code:
 
-That nar bundle format is essentially the concatenation of zero or more
-nars along with metadata for each store item it contains: its file name,
-references, corresponding derivation, and a digital signature.
+@enumerate
+@item
+Export the OpenPGP keys of past and present committers with @command{gpg
+--export} and store them in @file{.key} files, by default in a branch
+named @code{keyring} (we recommend making it an @dfn{orphan branch}).
 
-When exporting, the daemon digitally signs the contents of the archive,
-and that digital signature is appended.  When importing, the daemon
-verifies the signature and rejects the import in case of an invalid
-signature or if the signing key is not authorized.
-@c FIXME: Add xref to daemon doc about signatures.
+@item
+Introduce an initial @file{.guix-authorizations} in the channel's
+repository.  Do that in a signed commit (@pxref{Commit Access}, for
+information on how to sign Git commits.)
 
-The main options are:
+@item
+Advertise the channel introduction, for instance on your channel's web
+page.  The channel introduction, as we saw above, is the commit/key
+pair---i.e., the commit that introduced @file{.guix-authorizations}, and
+the fingerprint of the OpenPGP used to sign it.
+@end enumerate
 
-@table @code
-@item --export
-Export the specified store files or packages (see below).  Write the
-resulting archive to the standard output.
+Before pushing to your public Git repository, you can run @command{guix
+git-authenticate} to verify that you did sign all the commits you are
+about to push with an authorized key:
 
-Dependencies are @emph{not} included in the output, unless
-@option{--recursive} is passed.
+@example
+guix git authenticate @var{commit} @var{signer}
+@end example
 
-@item -r
-@itemx --recursive
-When combined with @option{--export}, this instructs @command{guix archive}
-to include dependencies of the given items in the archive.  Thus, the
-resulting archive is self-contained: it contains the closure of the
-exported store items.
+@noindent
+where @var{commit} and @var{signer} are your channel introduction.
+@xref{Invoking guix git authenticate}, for details.
 
-@item --import
-Read an archive from the standard input, and import the files listed
-therein into the store.  Abort if the archive has an invalid digital
-signature, or if it is signed by a public key not among the authorized
-keys (see @option{--authorize} below).
+Publishing a signed channel requires discipline: any mistake, such as an
+unsigned commit or a commit signed by an unauthorized key, will prevent
+users from pulling from your channel---well, that's the whole point of
+authentication!  Pay attention to merges in particular: merge commits
+are considered authentic if and only if they are signed by a key present
+in the @file{.guix-authorizations} file of @emph{both} branches.
 
-@item --missing
-Read a list of store file names from the standard input, one per line,
-and write on the standard output the subset of these files missing from
-the store.
+@cindex news, for channels
+@node Writing Channel News
+@section Writing Channel News
 
-@item --generate-key[=@var{parameters}]
-@cindex signing, archives
-Generate a new key pair for the daemon.  This is a prerequisite before
-archives can be exported with @option{--export}.  Note that this
-operation usually takes time, because it needs to gather enough entropy
-to generate the key pair.
+Channel authors may occasionally want to communicate to their users
+information about important changes in the channel.  You'd send them all
+an email, but that's not convenient.
 
-The generated key pair is typically stored under @file{/etc/guix}, in
-@file{signing-key.pub} (public key) and @file{signing-key.sec} (private
-key, which must be kept secret).  When @var{parameters} is omitted,
-an ECDSA key using the Ed25519 curve is generated, or, for Libgcrypt
-versions before 1.6.0, it is a 4096-bit RSA key.
-Alternatively, @var{parameters} can specify
-@code{genkey} parameters suitable for Libgcrypt (@pxref{General
-public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The
-Libgcrypt Reference Manual}).
+Instead, channels can provide a @dfn{news file}; when the channel users
+run @command{guix pull}, that news file is automatically read and
+@command{guix pull --news} can display the announcements that correspond
+to the new commits that have been pulled, if any.
 
-@item --authorize
-@cindex authorizing, archives
-Authorize imports signed by the public key passed on standard input.
-The public key must be in ``s-expression advanced format''---i.e., the
-same format as the @file{signing-key.pub} file.
+To do that, channel authors must first declare the name of the news file
+in their @file{.guix-channel} file:
 
-The list of authorized keys is kept in the human-editable file
-@file{/etc/guix/acl}.  The file contains
-@url{https://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
-s-expressions''} and is structured as an access-control list in the
-@url{https://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
-(SPKI)}.
+@lisp
+(channel
+  (version 0)
+  (news-file "etc/news.txt"))
+@end lisp
 
-@item --extract=@var{directory}
-@itemx -x @var{directory}
-Read a single-item archive as served by substitute servers
-(@pxref{Substitutes}) and extract it to @var{directory}.  This is a
-low-level operation needed in only very narrow use cases; see below.
+The news file itself, @file{etc/news.txt} in this example, must look
+something like this:
 
-For example, the following command extracts the substitute for Emacs
-served by @code{@value{SUBSTITUTE-SERVER}} to @file{/tmp/emacs}:
+@lisp
+(channel-news
+  (version 0)
+  (entry (tag "the-bug-fix")
+         (title (en "Fixed terrible bug")
+                (fr "Oh la la"))
+         (body (en "@@emph@{Good news@}!  It's fixed!")
+               (eo "Certe ĝi pli bone funkcias nun!")))
+  (entry (commit "bdcabe815cd28144a2d2b4bc3c5057b051fa9906")
+         (title (en "Added a great package")
+                (ca "Què vol dir guix?"))
+         (body (en "Don't miss the @@code@{hello@} package!"))))
+@end lisp
 
-@example
-$ wget -O - \
-  https://@value{SUBSTITUTE-SERVER}/nar/gzip/@dots{}-emacs-24.5 \
-  | gunzip | guix archive -x /tmp/emacs
-@end example
+While the news file is using the Scheme syntax, avoid naming it with a
+@file{.scm} extension or else it will get picked up when building the
+channel and yield an error since it is not a valid module.
+Alternatively, you can move the channel module to a subdirectory and
+store the news file in another directory.
 
-Single-item archives are different from multiple-item archives produced
-by @command{guix archive --export}; they contain a single store item,
-and they do @emph{not} embed a signature.  Thus this operation does
-@emph{no} signature verification and its output should be considered
-unsafe.
+The file consists of a list of @dfn{news entries}.  Each entry is
+associated with a commit or tag: it describes changes made in this
+commit, possibly in preceding commits as well.  Users see entries only
+the first time they obtain the commit the entry refers to.
 
-The primary purpose of this operation is to facilitate inspection of
-archive contents coming from possibly untrusted substitute servers
-(@pxref{Invoking guix challenge}).
+The @code{title} field should be a one-line summary while @code{body}
+can be arbitrarily long, and both can contain Texinfo markup
+(@pxref{Overview,,, texinfo, GNU Texinfo}).  Both the title and body are
+a list of language tag/message tuples, which allows @command{guix pull}
+to display news in the language that corresponds to the user's locale.
 
-@item --list
-@itemx -t
-Read a single-item archive as served by substitute servers
-(@pxref{Substitutes}) and print the list of files it contains, as in
-this example:
+If you want to translate news using a gettext-based workflow, you can
+extract translatable strings with @command{xgettext} (@pxref{xgettext
+Invocation,,, gettext, GNU Gettext Utilities}).  For example, assuming
+you write news entries in English first, the command below creates a PO
+file containing the strings to translate:
 
 @example
-$ wget -O - \
-  https://@value{SUBSTITUTE-SERVER}/nar/lzip/@dots{}-emacs-26.3 \
-  | lzip -d | guix archive -t
+xgettext -o news.po -l scheme -ken etc/news.txt
 @end example
 
-@end table
+To sum up, yes, you could use your channel as a blog.  But beware, this
+is @emph{not quite} what your users might expect.
 
 
 @c *********************************************************************
-- 
2.28.0

bug#43482: [PATCH v2 1/2] doc: Update the master menu.

[Ludovic Courtès]

Hi,

zimoun <zimon.toutoune@gmail.com> skribis:

> * doc/guix.texi: Update the master menu.

[...]

> The sectioning becomes:
>
> 1.  Specifying Additional Channels     (was 3.)
> 2.  Using a Custom Guix Channel        (was 2.)
> 3.  Replicating Guix                   (was 9.)
> 4.  Channel Authentication             (was 1.)
> 5.  Primary URL                        (was 7.)
> 6.  Creating a Channel                 (reworded)
> 7.  Package Modules in a Sub-directory (was 5.)
> 8.  Declaring Channel Dependencies     (was 4.)
> 9.  Specifying Channel Authorizations  (was 6.)
> 10. Writing Channel News               (was 8.)
>
> * doc/guix.texi (Channels): Move section to chapter.
> Reorder the chapter.
> Minor tweaks to keep uniformity.
> Update the master menu.

Applied, thanks!

Ludo’.