doc: Write about patch submission and packaging guidelines.

* HACKING: Update the command names from `guix-build' to `guix build' & co.
  (Submitting Patches, Packaging Guidelines): New sections.
* doc/guix.texi (Contributing): New section.

2 files changed, 62 insertions, 33 deletions

diff --git a/HACKING b/HACKING
index 05ba8324b3..413ba737d9 100644
--- a/HACKING
+++ b/HACKING
@@ -14,7 +14,7 @@ Copyright © 2012, 2013 Ludovic Courtès <ludo@gnu.org>
 Command-line tools can be used even if you have not run "make install".
 To do that, prefix each command with ‘./pre-inst-env’, as in:
 
-  ./pre-inst-env guix-build --help
+  ./pre-inst-env guix build --help
 
 Similarly, for a Guile session using the Guix modules:
 
@@ -40,6 +40,16 @@ addition to that, you must not miss [[http://www.emacswiki.org/emacs/ParEdit][Pa
 directly operate on the syntax tree, such as raising an s-expression or
 wrapping it, swallowing or rejecting the following s-expression, etc.
 
+* Packaging Guidelines
+
+The GNU distribution is about respecting the freedom of users.  Consequently,
+it contains only free software as defined at
+http://www.gnu.org/philosophy/free-sw.html .
+
+In addition, we follow the [[http://www.gnu.org/distros/free-system-distribution-guidelines.html][free software distribution guidelines]].  Among other
+things, this means that the distribution tries hard not to steer users towards
+obtaining information about non-free software.
+
 * Adding new packages
 
 Package recipes in Guix look like this:
@@ -68,22 +78,55 @@ Package recipes in Guix look like this:
 #+END_SRC
 
 Such a recipe can be written by hand, and then tested by running
-‘./pre-inst-env guix-build nettle’.
+‘./pre-inst-env guix build nettle’.
 
 When writing the recipe, the base32-encoded SHA256 hash of the source
 code tarball, which can be seen in the example above, can be obtained by
 running:
 
-  guix-download http://ftp.gnu.org/gnu/nettle/nettle-2.5.tar.gz
+  guix download http://ftp.gnu.org/gnu/nettle/nettle-2.5.tar.gz
 
 Alternatively, it is possible to semi-automatically import recipes from
 the [[http://nixos.org/nixpkgs/][Nixpkgs]] software distribution using this command:
 
-  guix-import /path/to/nixpkgs/checkout nettle
+  guix import /path/to/nixpkgs/checkout nettle
 
 The command automatically fetches and converts to Guix the “Nix
 expression” of Nettle.
 
+* Submitting Patches
+
+Development is done using the Git distributed version control system.  Thus,
+access to the repository is not strictly necessary.  We welcome contributions
+in the form of patches as produced by ‘git format-patch’ sent to
+bug-guix@gnu.org.  Please write commit logs in the [[http://www.gnu.org/prep/standards/html_node/Change-Logs.html#Change-Logs][GNU ChangeLog format]].
+
+As you become a regular contributor, you may find it convenient to have write
+access to the repository (see below.)
+
+* Commit Access
+
+For frequent contributors, having write access to the repository is
+convenient.  When you deem it necessary, feel free to ask for it on the
+mailing list.  When you get commit access, please make sure to follow the
+policy below (discussions of the policy can take place on bug-guix@gnu.org.)
+
+Non-trivial patches should always be posted to bug-guix@gnu.org (trivial
+patches include fixing typos, etc.)
+
+For patches that just add a new package, and a simple one, it’s OK to commit,
+if you’re confident (which means you successfully built it in a chroot setup.)
+Likewise for package upgrades.  We have a mailing list for commit
+notifications (guix-commits@gnu.org), so people can notice.  Before pushing
+your changes, make sure to run ‘git pull --rebase’.
+
+For anything else, please post to bug-guix@gnu.org and leave time for a
+review, without committing anything.  If you didn’t receive any reply
+after two weeks, and if you’re confident, it’s OK to commit.
+
+That last part is subject to being adjusted, allowing individuals to commit
+directly on non-controversial changes on parts they’re familiar with.
+
 * Porting the Guix distro on a new platform
 
 ** Introduction
@@ -137,7 +180,7 @@ GCC, libc, etc. need to be built.  To that end, run the following
 commands:
 
 #+BEGIN_SRC sh
-  ./pre-inst-env guix-build -K                                    \
+  ./pre-inst-env guix build -K                                    \
       -e '(@ (gnu packages make-bootstrap) %bootstrap-tarballs)'  \
       --system=i686-linux
 
@@ -174,30 +217,3 @@ shown above.  For example, all the binaries (except for glibc) must be
 statically-linked; the bootstrap Guile must be relocatable (see patch in
 the Guix distro); the static-binaries tarball must contain the same
 programs (Coreutils, Grep, sed, Awk, etc.); and so on.
-
-* Commit Access
-
-Development is done using the Git distributed version control system.  Thus,
-access to the repository is not strictly necessary.  We welcome contributions
-in the form of patches as produced by ‘git format-patch’ sent to
-bug-guix@gnu.org.
-
-However, for frequent contributors, having write access to the repository is
-convenient.  When you get commit access, please make sure to follow the policy
-below (discussions of the policy can take place on bug-guix@gnu.org.)
-
-Non-trivial patches should always be posted to bug-guix@gnu.org (trivial
-patches include fixing typos, etc.)
-
-For patches that just add a new package, and a simple one, it’s OK to commit,
-if you’re confident (which means you successfully built it in a chroot setup.)
-Likewise for package upgrades.  We have a mailing list for commit
-notifications (guix-commits@gnu.org), so people can notice.  Before pushing
-your changes, make sure to run ‘git pull --rebase’.
-
-For anything else, please post to bug-guix@gnu.org and leave time for a
-review, without committing anything.  If you didn’t receive any reply
-after two weeks, and if you’re confident, it’s OK to commit.
-
-That last part is subject to being adjusted, allowing individuals to commit
-directly on non-controversial changes on parts they’re familiar with.
diff --git a/doc/guix.texi b/doc/guix.texi
index 68d45d2a5f..02fb9982c1 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -82,6 +82,7 @@ Documentation License.''
 * Programming Interface::       Using Guix in Scheme.
 * Utilities::                   Package management commands.
 * GNU Distribution::            Software for your friendly GNU system.
+* Contributing::                Your help needed!
 
 * Acknowledgments::             Thanks!
 * GNU Free Documentation License::  The license of this manual.
@@ -1439,10 +1440,22 @@ tight integration of GNU components, and an emphasis on programs and
 tools that help users exert that freedom.
 
 Building this distribution is a cooperative effort, and you are invited
-to join!  Please get in touch with us on @email{bug-guix@@gnu.org}.  We
+to join!  @ref{Contributing}, for information about how you can help.
+
+@c *********************************************************************
+@node Contributing
+@chapter Contributing
+
+This project is a cooperative effort, and we need your help to make it
+grow!  Please get in touch with us on @email{bug-guix@@gnu.org}.  We
 welcome ideas, bug reports, patches, and anything that may be helpful to
 the project.
 
+Please see the
+@url{http://git.savannah.gnu.org/cgit/guix.git/tree/HACKING,
+@file{HACKING} file} that comes with the Guix source code for practical
+details about contributions.
+
 
 @c *********************************************************************
 @node Acknowledgments