DOC: Overview of Nixpkgs/channels/Hydra/tests (close #11263)

What I missed when I began using Nix and NixOS was a clear overview of
how packages, channels, Hydra, the master branch and updates to channels
relate to each other.

I've noticed I am not the only one, given the amount of times these
questions pop up.

For now I propose to include this in the Nixpkgs manual, since this
seems to be the best fit. However, I think it would be good to include
this in either a new manual, i.e., a user manual, or an 'official'
tutorial.

3 files changed, 53 insertions, 21 deletions

diff --git a/doc/default.nix b/doc/default.nix
index 7e41380d6358..65e12254f78d 100644
--- a/doc/default.nix
+++ b/doc/default.nix
@@ -43,6 +43,11 @@ stdenv.mkDerivation {
     cp -s '${sources-langs}'/* ./languages-frameworks
   ''
   + toDocbook {
+      inputFile = ./introduction.md;
+      outputFile = "introduction.xml";
+      useChapters = true;
+    }
+  + toDocbook {
       inputFile = ./haskell-users-guide.md;
       outputFile = "haskell-users-guide.xml";
       useChapters = true;
diff --git a/doc/introduction.md b/doc/introduction.md
new file mode 100644
index 000000000000..618251a6e156
--- /dev/null
+++ b/doc/introduction.md
@@ -0,0 +1,48 @@
+---
+title: Introduction
+author: Frederik Rietdijk
+date: 2015-11-25
+---
+
+# Introduction
+
+The Nix Packages collection (Nixpkgs) is a set of over 30,000 packages for the
+[Nix package manager](http://nixos.org/nix/), released under a [permissive MIT/X11 license](https://github.com/NixOS/nixpkgs/blob/master/COPYING).
+Packages are available for several architectures, and can be used with the Nix package manager
+on most GNU/Linux distributions as well as NixOS.
+
+This manual describes how to write packages for the Nix Packages collection
+(Nixpkgs). Thus it’s for packagers and developers who want to add packages to
+Nixpkgs. If you like to learn more about the Nix package manager and the Nix
+expression language, then you are kindly referred to the [Nix manual](http://nixos.org/nix/manual/).
+
+## Overview of Nixpkgs
+
+Nix expressions describe how to build packages from source and are collected in
+the [nixpkgs repository](https://github.com/NixOS/nixpkgs). Also included in the
+collection are Nix expressions for [NixOS modules](http://nixos.org/nixos/manual/index.html#sec-writing-modules). With
+these expressions the Nix package manager can build binary packages.
+
+Packages, including the Nix packages collection, are distributed through
+[channels](http://nixos.org/nix/manual/#sec-channels). The collection is
+distributed for users of Nix on non-NixOS distributions through the channel
+`nixpkgs`. Users of NixOS generally use one of the `nixos-*` channels, e.g.
+`nixos-15.09`, which includes all packages and modules for the stable NixOS
+15.09. The channels of the stable NixOS releases are generally only given
+security updates. More up to date packages and modules are available via the
+`nixos-unstable` channel.
+
+Both `nixos-unstable` and `nixpkgs` follow the `master` branch of the Nixpkgs
+repository, although both do lag the `master` branch by generally [a couple of days](http://howoldis.herokuapp.com/). Updates to a channel are distributed as
+soon as all tests for that channel pass, e.g. [this table](http://hydra.nixos.org/job/nixpkgs/trunk/unstable#tabs-constituents)
+shows the status of tests for the `nixpkgs` channel.
+
+The tests are conducted by a cluster called [Hydra](http://nixos.org/hydra/),
+which also builds binary packages from the Nix expressions in Nixpkgs. As soon
+as a channel is updated, the binaries are made available via a [binary cache](https://cache.nixos.org). Until the channel updates, binaries that have
+already been built, are available via [Hydra's binary cache](https://hydra.nixos.org).
+
+The current Nix expressions of the channels are available in the
+[`nixpkgs-channels`](https://github.com/NixOS/nixpkgs-channels) repository,
+which has branches corresponding to the available channels. There is also the
+Nixpkgs Monitor which keeps track of updates and security vulnerabilities.
diff --git a/doc/introduction.xml b/doc/introduction.xml
deleted file mode 100644
index 577b739e7d18..000000000000
--- a/doc/introduction.xml
+++ /dev/null
@@ -1,21 +0,0 @@
-<chapter xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xml:id="chap-introduction">
-
-<title>Introduction</title>
-
-<para>This manual tells you how to write packages for the Nix Packages
-collection (Nixpkgs).  Thus it’s for packagers and developers who want
-to add packages to Nixpkgs.  End users are kindly referred to the
-<link xlink:href="http://hydra.nixos.org/job/nix/trunk/tarball/latest/download-by-type/doc/manual">Nix
-manual</link>.</para>
-
-<para>This manual does not describe the syntax and semantics of the
-Nix expression language, which are given in the Nix manual in the
-<link
-xlink:href="http://hydra.nixos.org/job/nix/trunk/tarball/latest/download-by-type/doc/manual/#chap-writing-nix-expressions">chapter
-on writing Nix expressions</link>.  It only describes the facilities
-provided by Nixpkgs to make writing packages easier, such as the
-standard build environment (<literal>stdenv</literal>).</para>
-
-</chapter>