doc: Document bulk updates.

* doc/contributing.texi (Bulk updates): New section describing update
technique for collection of packages.

Change-Id: Ic67978a6c8e0140980a0ede968f7e411faf23a1d
Signed-off-by: jgart <jgart@dismail.de>

1 files changed, 35 insertions, 0 deletions

diff --git a/doc/contributing.texi b/doc/contributing.texi
index f210a3fc76..2ae4844f71 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -1099,6 +1099,7 @@ needed is to review and apply the patch.
 * Synopses and Descriptions::   Helping users find the right package.
 * Snippets versus Phases::      Whether to use a snippet, or a build phase.
 * Cyclic Module Dependencies::  Going full circle.
+* Bulk updates::                This Little Maneuver's Gonna Cost Us 51 Years
 * Emacs Packages::              Your Elisp fix.
 * Python Modules::              A touch of British comedy.
 * Perl Modules::                Little pearls.
@@ -1425,6 +1426,40 @@ Care would need to be taken to ensure the above procedure is only ever
 used in a package delayed fields or within another procedure also not
 called at the top level.
 
+@node Bulk updates
+@subsection Bulk updates
+
+@cindex packaging, maintenance
+Sometimes you may need to update a monotonic collection of grouped
+packages, in particular module e.g. @code{(gnu packages astronomy)} - it
+would require refreshing package versions, creating commits following
+guidelines and test them. Let's say there are 200+ packages which have
+fresh versions, you may deal with that task by applying the following
+technique.
+
+Enter a development shell in your local Guix checkout, assuming you
+already run @code{bootstrap} and @code{configer}:
+
+@example
+~$ guix shell --development guix
+[env: /gnu/store/lzxbi1ps43msyw7m5wblziy8mj6hw5kw-profile]
+> ./pre-inst-env guix refresh --select=module:astronomy --update
+> ./pre-inst-env etc/commiter.scm
+@end example
+
+The first command will update all packages in @code{(gnu packages
+astronomy)} to the latest versions and write changes back to the file.
+The second will invoke @code{etc/commiter.scm} script, a helper script
+aiming exactly for larger scale updates; it will identify each package
+diff and create corresponding commits with correct style.
+
+If your machine is powerful enough you may check that the whole
+collection has no regression and still can be built successfully:
+@example
+[env: /gnu/store/lzxbi1ps43msyw7m5wblziy8mj6hw5kw-profile]
+> ./pre-inst-env guix build $(./pre-inst-env guix package -A | awk '/astronomy.scm/{print $1"@"$2}')
+@end example
+
 @node Emacs Packages
 @subsection Emacs Packages