doc: update HACKING.

* HACKING: update for some current realities.

1 files changed, 139 insertions, 28 deletions

diff --git a/HACKING b/HACKING
index 886f6901a..82b77ed54 100644
--- a/HACKING
+++ b/HACKING
@@ -3,21 +3,26 @@
 
 * This file attempts to describe the conventions to use when hacking automake.
 
+* After git checkout from Savannah, can do initial build with, e.g.:
+  $ ./bootstrap && ./configure --prefix=/tmp/amdev && make
+
 ============================================================================
 = Administrivia
 
 * The correct response to most actual bugs is to write a new test case
   which demonstrates the bug.  Then fix the bug, re-run the test suite,
-  and check everything in.
+  and check everything in.  Run the test suite in parallel.
 
 * If you incorporate a change from somebody on the net:
-  - First, if it is a large change, you must make sure they have
+  - First, if it is not a tiny change, you must make sure they have
     signed the appropriate paperwork.
   - 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,
-  mention the bug number in the commit message.
+* If a change fixes or adds a test, mention the test in the commit
+  message.  If a change fixes a bug registered in the Automake debbugs
+  tracker, mention the bug number in the commit message, using
+  the short url form, like https://bugs.gnu.org/1234.  See section below
+  about commit messages.
 
 * If somebody reports a new bug, mention their name in the commit message
   that fixes or exposes the bug, and add a line for them in THANKS.
@@ -35,7 +40,7 @@
   updated by hand whenever the GPL gets updated (which shouldn't happen
   that often anyway :-)
 
-* All changes that are not *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
@@ -47,10 +52,26 @@
   Automake debbugs tracker, to keep the idea more visible, and have the
   discussions surrounding it easily archived in a central place.
 
+===========================================================================
+= 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:
+
+  $ guix environment automake --ad-hoc \
+      gettext help2man texinfo libtool flex bison dejagnu zip icedtea \
+      python gcc-toolchain gfortran pkg-config vala
+
+  For other environments, you'll need to install the equivalent.
+
 ============================================================================
 = Naming
 
-* We've adopted the convention that internal AC_SUBSTs and make variables
+* Automake's convention is that internal AC_SUBSTs and make variables
   should be named with a leading 'am__', and internally generated targets
   should be named with a leading 'am--'.  This convention, although in
   place from at least February 2001, isn't yet universally used.
@@ -152,20 +173,6 @@
 * For more information, refer to the extensive discussion associated
   with automake bug#13578.
 
-===========================================================================
-= 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:
-
-  $ guix environment automake --ad-hoc \
-      gettext help2man texinfo libtool flex bison dejagnu zip icedtea \
-      python gcc-toolchain gfortran pkg-config vala
-
 ============================================================================
 = Working with git
 
@@ -177,7 +184,7 @@
   latest stable version of Autoconf installed and available early
   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)
+  (per https://bugs.gnu.org/11347)
 
 * The Automake git tree currently carries three basic branches: 'master',
   'next' and 'maint'.
@@ -225,6 +232,20 @@
   it in the 'experimental/*' namespace; for example, a rewindable branch
   dealing with Vala support could be named like "experimental/vala-work".
 
+* If you need to trivially fix a change after a commit, e.g., a typo in
+  the NEWS entry, edit the file and then:
+    git commit --amend --no-edit NEWS
+    git commit --amend --date="$(date -R)" # update date of commit
+
+* If you want to just completely lose your local changes:
+    git fetch && git reset --hard origin && git checkout && git submodule update
+  (the submodule stuff is for gnulib).
+
+* The preferred way to create a patch to mail around:
+    git format-patch --stdout -1 >/tmp/some-patch.diff
+  which can then be applied with:
+    git am mboxfile
+
 ============================================================================
 = Writing a good commit message
 
@@ -264,19 +285,21 @@
     * some/file (func1): Improved frobnication.
     (func2): Adjusted accordingly.
     * another/file (foo, bar): Likewise.
-    * tests/foo.tap: New test.
-    * tests/Makefile.am (TESTS): Add it.
+    * t/foo.sh: New test.
+    * t/list-of-tests.mk (handwritten_TESTS): Add it.
+    * doc/automake.texi (Some Node): Document it.
+    * NEWS: mention it.
 
 * If your commit fixes an automake bug registered in the tracker (say
   numbered 1234), you should put the following line after the summary
   line:
 
-      This change fixes automake bug#1234.
+      Fixes automake bug https://bugs.gnu.org/1234.
 
 * If your commit is just related to the given bug report, but does not
   fix it, you might want to add a line like this instead:
 
-      This change is related to automake bug#1234.
+      Related to automake bug https://bugs.gnu.org/1234.
 
 * When referring to older commits, use 'git describe' output as pointer.
   But also try to identify the given commit by date and/or summary line
@@ -284,7 +307,7 @@
 
       Since yesterday's commit, v1.11-2019-g4d2bf42, ...
 
-      ... removed in commit 'v1.11-1674-g02e9072' of 01-01-2012,
+      ... removed in commit 'v1.11-1674-g02e9072' of 2012-01-01,
       "dist: ditch support for lzma"...
 
 * If the commit is a tiny change that is exempt from copyright paperwork, the
@@ -293,6 +316,8 @@
 
       Copyright-paperwork-exempt: yes
 
+* Generally write the commit message in present tense.
+
 ============================================================================
 = Test suite
 
@@ -307,7 +332,93 @@
   tested by your new tests.
 
 * To run the tests, you should install expect, shar, language compilers,
-  gettext macros. Anything you don't install won't be tested.
+  gettext macros.  Anything you don't install won't be tested.  The test
+  suite will report on tests skipped due to software not available.
+
+* You can run a single test, with, e.g.,
+
+    make check TESTS='t/aclocal-acdir.sh'
+
+  where t/aclocal-acdir.sh can be any t/*.sh test, including a new one
+  you are writing.  You may want to add --no-print-dir to silence GNU
+  make about the many cd commands, and/or env VERBOSE=1 to get more
+  information about what make is running.
+
+* Then check t/test-suite.log for the overall results.  The directory
+  t/TESTNAME.dir is where the work will be left, if the test fails.
+  During development of a new test, you want to end it with "exit 33"
+  (or whatever) to make it fail even when it would succeed, so you can
+  inspect the test directory to be sure things worked as expected.
+
+  You can also set keep_testdirs=yes on the command line to keep the
+  *.dir results.
+
+* Run the test suite in parallel (e.g., "make -j12 check"), both so it
+  doesn't take forever and because that is what most users will do.  You
+  can also parallelize the makes that run inside each test with, e.g.:
+
+    make check AM_TESTSUITE_MAKE="make -j$(( 1*$(nproc) + 1 ))"
+
+  If you like, try different levels of parallelization to see what
+  runs the fastest on your machine.
+
+* Run "make maintainer-check" before commit.  Watch out for trailing spaces.
+
+* It is good to run also run "make -j12 distcheck" before pushing a
+  commit since that exercises yet more testing, after "make -j12 check"
+  succeeds.
+
+* Use make V=1 to un-silence (some) of what make does.
+
+* To set up a new test, first write the test file in t/good-name.sh.
+  Choose a name that fits with existing ones, as best you can devise.
+
+  - You'll likely want to copy material from an existing test, which is
+  fine and good; depending on how much is copied, it may be useful to
+  mention the other test(s) you used.
+
+  - Nevertheless, start the copyright year list in the new file fresh,
+  with the current year.
+
+  - You can run the new test on its own with
+    make check TESTS='t/good-name.sh'
+
+  - At some point before releasing, add the test to the appropriate
+  variable in t/list-of-tests.mk, most likely the (alphabetical)
+  handwritten_TESTS.
+
+============================================================================
+= Bug tracker
+
+* Automake uses the debbugs instance at https://bugs.gnu.org.  Email
+  from the tracker is sent to bug-automake@gnu.org, and vice versa.
+  (https://gnu.org/s/automake for all the mailing lists; you should subscribe.)
+
+* To see all open bugs (and recently closed ones):
+    https://debbugs.gnu.org/cgi/pkgreport.cgi?pkg=automake
+
+* For a full search form, initialized to show bugs tagged confirmed:
+    https://debbugs.gnu.org/cgi/pkgreport.cgi?package=automake;include=tags%3Aconfirmed
+
+* We use the "confirmed" tag to mean bugs that have been reviewed, are
+  evidently valid, but no one is currently working or plans to work on
+  them.  Thus they are good candidates for new volunteers to get involved.
+
+* To download the so-called maintainer mbox for a bug, say 12345:
+    https://debbugs.gnu.org/cgi/bugreport.cgi?bug=12345;mbox=yes;mboxmaint=yes
+  Only the maintainer mbox consistently has the bug# prefix on Subject:
+  lines, so it is generally the most usable.
+
+* To close a bug, you can mail (or bcc) to 12345-done@debbugs.gnu.org.
+  It's best to do this with a note saying that the bug is being closed
+  because the fix was pushed, or whatever the reason.
+
+* To add tags "help" and "confirmed" to bug 12345, mail to
+  control@debbugs.gnu.org with a one-line body:
+    tags 35322 + help confirmed
+
+* In general, all bug operations are done by mail.  Reference information:
+    https://debbugs.gnu.org/server-control.html # dev info
 
 ============================================================================
 = Release procedure