doc: HACKING updates.

* HACKING: some additional tidbits.

1 files changed, 33 insertions, 18 deletions

diff --git a/HACKING b/HACKING
index e8b7034e3..886f6901a 100644
--- a/HACKING
+++ b/HACKING
@@ -1,8 +1,7 @@
 ============================================================================
 = This file
 
-* This file attempts to describe the rules to use when hacking
-  automake.
+* This file attempts to describe the conventions to use when hacking automake.
 
 ============================================================================
 = Administrivia
@@ -14,7 +13,7 @@
 * If you incorporate a change from somebody on the net:
   - First, if it is a large change, you must make sure they have
     signed the appropriate paperwork.
-  - Second, be sure to add their name and email address to THANKS.
+  - Second, add their name and email address to THANKS.
 
 * If a change fixes a test, mention the test in the commit message.
   If a change fixes a bug registered in the Automake debbugs tracker,
@@ -27,15 +26,16 @@
   sure to add a test case for it, and to reference such test case from
   a proper Texinfo comment.
 
-* Some files in the automake package are not owned by automake; these
-  files are listed in the $(FETCHFILES) variable in Makefile.am.  They
-  should never be edited here.  Almost all of them can be updated from
-  respective upstreams with "make fetch" (this should be done especially
-  before releases).  The only exception is the 'lib/COPYING' (from FSF),
-  which should be updated by hand whenever the GPL gets updated (which
-  shouldn't happen that often anyway :-)
+* Some files in the automake package are not owned by automake (many by
+  gnulib, https://gnu.org/s/gnulib); these files are listed in the
+  $(FETCHFILES) variable in Makefile.am.  They should never be edited
+  here.  All but one of them can be updated from respective upstreams
+  with "make fetch" (this should be done especially before releases).
+  The only exception is 'lib/COPYING' (from FSF), which should be
+  updated by hand whenever the GPL gets updated (which shouldn't happen
+  that often anyway :-)
 
-* Changes other than *trivial* bug fixes must be mentioned in NEWS.
+* All changes that are not *trivial* bug fixes must be mentioned in NEWS.
 
 * Changes which are potentially controversial, require a non-trivial
   plan, or must be implemented gradually with a roadmap spanning several
@@ -61,14 +61,20 @@
   variable begins with the underscore character.  Yay for them.
   I changed the target naming convention just to be safe.
 
+* If you'd like to read some general background on automake and the
+  other GNU autotools, you might try this not-too-long web page (not
+  affiliated with GNU):
+  https://www.linux.com/news/best-practices-autotools/
+
 ============================================================================
 = Editing '.am' files
 
-* Always use $(...) and not ${...}
+* For variables, always use $(...) and not ${...}.
 
 * Prefer ':' over 'true', mostly for consistency with existing code.
 
-* Use '##' comments liberally.  Comment anything even remotely unusual.
+* Use '##' comments liberally.  Comment anything even remotely unusual,
+  and even usual things, to help future readers of the code understand.
 
 * Never use basename or dirname.  Instead, use sed.
 
@@ -139,8 +145,9 @@
 
 * Major releases can introduce backward-incompatibilities (albeit such
   incompatibilities should be announced well in advance, and a smooth
-  transition plan prepared for them), and try more risking and daring
-  refactorings and code cleanups.
+  transition plan prepared for them), and try more risky and daring
+  refactorings and code cleanups.  Still, backward compatibilities are
+  extremely undesirable and should be avoided at all costs.
 
 * For more information, refer to the extensive discussion associated
   with automake bug#13578.
@@ -148,6 +155,9 @@
 ===========================================================================
 = Setting the development environment
 
+* In development, ./GNUmakefile is used, not (the generated) ./Makefile.
+  Run make V=1 to see the commands that are run.
+
 * The required and optional dependencies used by Automake and its test suite
   can be automatically fetched using the GNU Guix package manager with the
   following command:
@@ -165,7 +175,9 @@
   be the same as you would get if you install this version of
   automake and use it to generate those files.  Be sure to have the
   latest stable version of Autoconf installed and available early
-  in your PATH.
+  in your PATH. To get a faithful and correct rebuild, run:
+    ./bootstrap && ./config.status --recheck && make clean all
+  (per https://debbugs.gnu.org/cgi/bugreport.cgi?bug=11347)
 
 * The Automake git tree currently carries three basic branches: 'master',
   'next' and 'maint'.
@@ -284,6 +296,8 @@
 ============================================================================
 = Test suite
 
+* See file 't/README' for more information.
+
 * Use "make check" and "make maintainer-check" liberally.
 
 * Export the 'keep_testdirs' environment variable to "yes" to keep
@@ -292,7 +306,8 @@
 * Use perl coverage information to ensure your new code is thoroughly
   tested by your new tests.
 
-* See file 't/README' for more information.
+* To run the tests, you should install expect, shar, language compilers,
+  gettext macros. Anything you don't install won't be tested.
 
 ============================================================================
 = Release procedure
@@ -391,7 +406,7 @@
 
 -----
 
-Copyright (C) 2003-2020 Free Software Foundation, Inc.
+Copyright (C) 2003-2021 Free Software Foundation, Inc.
 
 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by