Update HACKING.

* HACKING: Mention the linear git history, how to work with ChangeLog,
how to run a testdir, where to find the gnulib-tool tests, and where are
the continuous integrations.

diff --git a/ChangeLog b/ChangeLog
index 462823888d865876b9cb137ab195fa1d2d37d5f1..00936c2d208a731cee7b404502c1fcda119cd27a 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2024-04-23  Bruno Haible  <bruno@clisp.org>
+
+       Update HACKING.
+       * HACKING: Mention the linear git history, how to work with ChangeLog,
+       how to run a testdir, where to find the gnulib-tool tests, and where are
+       the continuous integrations.
+
 2024-04-22  Bruno Haible  <bruno@clisp.org>
 
        gnulib-tool: Fix trouble caused by Python's bytecode cache.

diff --git a/HACKING b/HACKING
index 74f298081d62a8737aae3002d7c0bff12793e84f..7a23a339821c1be54efacb52d2699416f8bd70d0 100644 (file)
--- a/HACKING
+++ b/HACKING
@@ -14,10 +14,30 @@ Using git
   to update the copyright year of each modified file (since we don't run
   "make update-copyright" on the stable branches).
 
+* We use a linear git history — no merges. To work in this setting, it's
+  recommended that you configure git with 'git config pull.rebase = true'.
+
+* Before pushing a commit, it is highly recommended that you review it in
+  its entirety. The easiest way to do so is to run
+    $ gitk
+
 * We update the ChangeLog by hand.  The commit message is usually identical
   to the ChangeLog entry, with the date and author line removed, with
   the leading tabs removed, and with a blank line after the commit's
   summary line.
+  In order to work efficiently with ChangeLog files, it is recommended that
+  you configure git to use the git-merge-changelog driver; see the instructions
+  in the lib/git-merge-changelog.c file.
+  Note: This driver reasonably keeps the ChangeLog entries together; however,
+  it does not always keep them in the order you would desire. For example,
+  when you had prepared a commit, you try to "git push" it but that fails due
+  to someone else's commit that came earlier, what you need to do is:
+    1. $ git pull
+    2. Verify that your ChangeLog entry is still the top-most one.
+    3. If it is not, then edit ChangeLog to move it to the top, and
+       $ git commit --amend ChangeLog
+    4. $ gitk
+    5. $ git push
 
 * When you commit a contributor's patch, please
   - add a reasonable ChangeLog entry in the usual style (meaningful
@@ -52,6 +72,30 @@ When adding a module, add a unit test module as well.  This is our best
 chance to catch portability problems.
 
 
+Maintaining high quality
+========================
+
+It is a good idea to occasionally create a testdir of all of Gnulib:
+  $ rm -rf ../testdir-all; ./gnulib-tool --create-testdir --dir=../testdir-all --with-c++-tests --without-privileged-tests --single-configure `./all-modules`
+and test this directory on various plaforms:
+  - Linux/glibc systems,
+  - Linux/musl systems,
+  - macOS,
+  - FreeBSD,
+  - NetBSD,
+  - OpenBSD,
+  - AIX,
+  - Solaris 10 and 11,
+  - Cygwin,
+  - Haiku,
+  - Android,
+  - and other platforms of your choice.
+
+There is a continuous integration that regularly performs this testing
+on a Linux/glibc system: https://gitlab.com/gnulib/gnulib-ci
+But this will catch only the most blatant mistakes.
+
+
 Warning Options
 ===============
 
@@ -519,6 +563,29 @@ Again, use your own judgement to determine whether to fix or ignore a
 specific warning.
 
 
+Information for gnulib-tool maintenance
+***************************************
+
+Running the unit tests
+======================
+
+The unit tests of gnulib-tool reside in the maint-tools repository, that is a
+satellite repository of the main gnulib repository. Instructions how to obtain
+it are in https://savannah.gnu.org/git/?group=gnulib .
+
+To run the unit tests of gnulib-tool.sh:
+  $ cd maint-tools/gnulib-tool-tests/
+  $ GNULIB_TOOL_IMPL=sh ./test-all.sh
+
+To run the unit tests of gnulib-tool.py:
+  $ cd maint-tools/gnulib-tool-tests/
+  $ GNULIB_TOOL_IMPL=py ./test-all.sh
+
+It is *mandatory* that you run the test suite before pushing any change to
+gnulib-tool.sh or gnulib-tool.py! If you fail to do so, and your change contains
+a bug, it will start to affect users immediately.
+
+
 Debugging the Python implementation of gnulib-tool
 ==================================================
 
@@ -571,3 +638,10 @@ With Eclipse and PyDev as IDE
   - Open GLImport.py.
   - On the left-hand border of this editor, do "Add breakpoint".
   - Run > Debug Configurations... > pick the duplicate. Press Debug.
+
+
+Maintaining high quality
+========================
+
+There is a continuous integration of gnulib-tool.py that runs the unit tests,
+at https://gitlab.com/gnulib/gnulib-tool-ci/ .