1 files changed, 34 insertions, 0 deletions
diff --git a/doc/manual/release-notes.xml b/doc/manual/release-notes.xml
index 8d0840d06e5f..c1dc6166d817 100644
--- a/doc/manual/release-notes.xml
+++ b/doc/manual/release-notes.xml
@@ -15,6 +15,40 @@
 <itemizedlist>
 
   <listitem>
+    <para>Nix has a new binary substituter mechanism: the
+    <emphasis>binary cache</emphasis>.  A binary cache contains
+    pre-built binaries of Nix packages.  Whenever Nix wants to build a
+    missing Nix store path, it will check a set of binary caches to
+    see if any of them has a pre-built binary of that path.  The
+    configuration setting <option>binary-caches</option> contains a
+    list of URLs of binary caches.  For instance, doing
+<screen>
+$ nix-env -i thunderbird --option binary-caches http://nixos.org/binary-cache
+</screen>
+    will install Thunderbird and its dependencies, using the available
+    pre-built binaries in <uri>http://nixos.org/binary-cache</uri>.
+    The main advantage over the old “manifest”-based method of getting
+    pre-built binaries is that you don’t have to worry about your
+    manifest being in sync with the Nix expressions you’re installing
+    from; i.e., you don’t need to run <command>nix-pull</command> to
+    update your manifest.  It’s also more scalable because you don’t
+    need to redownload a giant manifest file every time.
+    </para>
+
+    <para>A Nix channel can provide a binary cache URL that will be
+    used automatically if you subscribe to that channel.  If you use
+    the Nixpkgs or NixOS channels
+    (<uri>http://nixos.org/channels</uri>) you automatically get the
+    cache <uri>http://nixos.org/binary-cache</uri>.</para>
+
+    <para>Binary caches are created using <command>nix-push</command>.
+    For details on the operation and format of binary caches, see the
+    <command>nix-push</command> manpage.  More details are provided in
+    <link xlink:href="http://lists.science.uu.nl/pipermail/nix-dev/2012-September/009826.html">this
+    nix-dev posting</link>.</para>
+  </listitem>
+
+  <listitem>
     <para>Dashes are now valid as part of identifiers and attribute
     names.</para>
   </listitem>