From bb0cd90154d4bf113bfb34bfe184fedee32505b7 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sat, 17 Jul 2021 18:10:21 -0700 Subject: doc: update HACKING. * HACKING: update for some current realities. --- HACKING | 167 +++++++++++++++++++++++++++++++++++++++++++++++++++++----------- 1 file 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 -- cgit v1.2.1