1 files changed, 69 insertions, 15 deletions
diff --git a/doc/contributing.texi b/doc/contributing.texi
index 9f97788c0b..207efc4ee6 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -98,8 +98,14 @@ shell}:
 guix shell -D guix help2man git strace --pure
 @end example
 
-Run @command{./bootstrap} to generate the build system infrastructure
-using Autoconf and Automake.  If you get an error like this one:
+From there you can generate the build system infrastructure
+using Autoconf and Automake:
+
+@example
+./bootstrap
+@end example
+
+If you get an error like this one:
 
 @example
 configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES
@@ -120,17 +126,30 @@ export ACLOCAL_PATH=/usr/share/aclocal
 @xref{Macro Search Path,,, automake, The GNU Automake Manual}, for
 more information.
 
-Then, run @command{./configure --localstatedir=@var{directory}}, where
-@var{directory} is the @code{localstatedir} value used by your current
-installation (@pxref{The Store}, for information about this), usually
-@file{/var}.  Note that you will probably not run @command{make install}
-at the end (you don't have to) but it's still important to pass the
-right @code{localstatedir}.
+Then, run:
+
+@example
+./configure --localstatedir=/var
+@end example
+
+@noindent
+... where @file{/var} is the normal @code{localstatedir} value
+(@pxref{The Store}, for information about this).  Note that you will
+probably not run @command{make install} at the end (you don't have to)
+but it's still important to pass the right @code{localstatedir}.
+
+Finally, you can build Guix and, if you feel so inclined, run the tests
+(@pxref{Running the Test Suite}):
 
-Finally, you have to invoke @code{make && make check} to build Guix and
-run the tests (@pxref{Running the Test Suite}).  If anything fails, take
-a look at installation instructions (@pxref{Installation}) or send a
-message to the @email{guix-devel@@gnu.org, mailing list}.
+@example
+make
+make check
+@end example
+
+@noindent
+If anything fails, take a look at installation instructions
+(@pxref{Installation}) or send a message to the
+@email{guix-devel@@gnu.org, mailing list}.
 
 From there on, you can authenticate all the commits included in your
 checkout by running:
@@ -157,6 +176,18 @@ You are advised to run @command{make authenticate} after every
 changes to the repository.
 @end quotation
 
+After updating the repository, @command{make} might fail with an error
+similar to the following example:
+
+@example
+error: failed to load 'gnu/packages/dunst.scm':
+ice-9/eval.scm:293:34: In procedure abi-check: #<record-type <origin>>: record ABI mismatch; recompilation needed
+@end example
+
+This means that one of the record types that Guix defines (in this
+example, the @code{origin} record) has changed, and all of guix needs
+to be recompiled to take that change into account.  To do so, run
+@command{make clean-go} followed by @command{make}.
 
 @node Running Guix Before It Is Installed
 @section Running Guix Before It Is Installed
@@ -231,6 +262,24 @@ local source tree; it simply updates the @file{~/.config/guix/current}
 symlink (@pxref{Invoking guix pull}).  Run @command{git pull} instead if
 you want to upgrade your local source tree.
 
+Sometimes, especially if you have recently updated your repository,
+running @command{./pre-inst-env} will print a message similar to the
+following example:
+
+@example
+;;; note: source file /home/user/projects/guix/guix/progress.scm
+;;;       newer than compiled /home/user/projects/guix/guix/progress.go
+@end example
+
+This is only a note and you can safely ignore it.  You can get rid of
+the message by running @command{make -j4}.  Until you do, Guile will run
+slightly slower because it will interpret the code instead of using
+prepared Guile object (@file{.go}) files.
+
+You can run @command{make} automatically as you work using
+@command{watchexec} from the @code{watchexec} package.  For example,
+to build again each time you update a package file, you can run
+@samp{watchexec -w gnu/packages make -j4}.
 
 @node The Perfect Setup
 @section The Perfect Setup
@@ -1386,9 +1435,14 @@ what your usertag means.
 @cindex commit access, for developers
 Everyone can contribute to Guix without having commit access
 (@pxref{Submitting Patches}).  However, for frequent contributors,
-having write access to the repository can be convenient.  Commit access
-should not be thought of as a ``badge of honor'' but rather as a
-responsibility a contributor is willing to take to help the project.
+having write access to the repository can be convenient.  As a rule of
+thumb, a contributor should have accumulated fifty (50) reviewed commits
+to be considered as a committer and have sustained their activity in the
+project for at least 6 months.  This ensures enough interactions with
+the contributor, which is essential for mentoring and assessing whether
+they are ready to become a committer.  Commit access should not be
+thought of as a ``badge of honor'' but rather as a responsibility a
+contributor is willing to take to help the project.
 
 The following sections explain how to get commit access, how to be ready
 to push commits, and the policies and community expectations for commits