[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[automake-commit] branch master updated: doc: update HACKING.
[automake-commit] branch master updated: doc: update HACKING.
Sat, 17 Jul 2021 21:10:30 -0400
This is an automated email from the git hooks/post-receive script.
karl pushed a commit to branch master
in repository automake.
View the commit online:
The following commit(s) were added to refs/heads/master by this push:
new bb0cd90 doc: update HACKING.
bb0cd90 is described below
Author: Karl Berry <email@example.com>
AuthorDate: Sat Jul 17 18:10:21 2021 -0700
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 886f690..82b77ed 100644
@@ -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
* 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.
-* 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
+ (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
- 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 @@
+* 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"
+* 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)
+= Bug tracker
+* Automake uses the debbugs instance at https://bugs.gnu.org. Email
+ from the tracker is sent to firstname.lastname@example.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):
+* For a full search form, initialized to show bugs tagged confirmed:
+* 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:
+ 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 email@example.com.
+ 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
+ firstname.lastname@example.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
|[Prev in Thread]
||[Next in Thread]|
- [automake-commit] branch master updated: doc: update HACKING.,
Karl Berry <=