X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/abe6c89607d903de961df368d638837dc938505f..3e90f7c100988b1f90706e2212fec687d2cd7f52:/docs/README.developers

diff --git a/docs/README.developers b/docs/README.developers
index 8b9ecdf0..d834b5e9 100644
--- a/docs/README.developers
+++ b/docs/README.developers
@@ -8,6 +8,7 @@ local info best encoded in a comment) are encouraged to share their wisdom here.
 
 Following a commit checklist, the topics are organized alphabetically.
 
+
 ----------------
 commit checklist
 ----------------
@@ -21,10 +22,16 @@ commit checklist
 7. update/close bug report (with commit id)?
 8. notify nmh-users?
 
+A buildbot at http://orthanc.ca:8010/waterfall polls for new commits and
+builds them on a few platforms.  Keep an eye on its progress in case
+you've committed something non-portable.  (If you can provide another
+platform, contact the nmh-workers list.)
+
 
 ---------------------------------
 C library/system call usage notes
 ---------------------------------
+
 * Use m_mktemp2() or m_mktemp() instead of mkstemp(3) (see section on
   nmh temporary files below).
 * Use m_unlink() instead of unlink(3).
@@ -111,9 +118,16 @@ sbr/
     file.  These functions are of general use and are called from throughout
     nmh.
 
+SPECS/
+    Contains files such as RPM specs.
+
 test/
     The num unit test suite.
 
+tools/
+    "tools" contains tools, scripts, and supporting files used by the
+    developers while writing, debugging, and testing the code.
+
 uip/
     "uip" stands for "User Interface Programs".  Most nmh commands have a file
     in this directory named <command>.c containing the code for that command
@@ -156,6 +170,7 @@ to any new branches that you create:
 
     % git config branch.autosetuprebase always
 
+
 -------------------------------------------------------
 nmh-local functions to use in preference to OS versions
 -------------------------------------------------------
@@ -193,15 +208,24 @@ nmh test suite
 The nmh test suite is run through the Makefile, with "make check"
 or "make distcheck".
 
+In the nmh test suite, nmh programs to be tested should be invoked
+through the run_test or run_prog shell functions defined in
+test/common.sh.
+
+Instead of echoing test progress, use start_test()/finish_test()
+from tests/common.sh.  These will report the particular test name,
+within the test, only if there is a failure.
+
 To enable the use of valgrind, where available, set the environment
 variable NMH_VALGRIND to a non-null value.  However, a separate
 environment variable, VALGRIND_ME, triggers the use of valgrind in
 test/inc/test-eom-align because it greatly extends the duration of
 that test.
 
-In the nmh test suite, nmh programs to be tested should be invoked
-through the run_test or run_prog shell functions defined in
-test/common.sh.
+If valgrind complains about "serious error when reading debuginfo"
+from a library, either update or remove the debuginfo package for
+the offending library.
+
 
 -------------
 releasing nmh
@@ -216,11 +240,18 @@ here; the convention for release candidates is to use something like
 
     % git branch 1.5-release
 
-    Note you are still on the master branch at this point.  So mark that
-    master will now be post-1.5:
+    Note you are still on the master branch at this point.  Mark the
+    current revision as the branchpoint for the new release branch:
+
+    % git tag -a -m "This tag marks the point where we started the branch for 1.5" 1.5-branchpoint
+
+    Now mark the master branch with a post-release version number (the
+    convention here is to use VERSION+dev as the version number).
 
     % echo 1.5+dev > VERSION
-    % git commit VERSION; git push
+    % git commit VERSION
+    % git push
+    % git push --tags
 
     Then do:
 
@@ -235,6 +266,7 @@ here; the convention for release candidates is to use something like
  3. % git commit VERSION DATE; git push
 
  4. % git tag -a 1.5 -m 'Releasing nmh-1.5.'
+    % git push --tags
 
     Note that the new convention for tagging is to simply tag with the
     version number (tag formats in the past have varied).
@@ -283,3 +315,19 @@ here; the convention for release candidates is to use something like
     it assumes that we tag with nmh-x_x-release from now on]:
 
         http://git.savannah.gnu.org/cgit/nmh.git/diff/?h=nmh-1_5-release?h=nmh-1_4-release
+
+
+---------------
+after a release
+---------------
+
+Keep an eye on Debian's packaging, especially what patches they have to
+apply, and the results of their Lintian checker, which even includes
+spelling errors in man pages and binaries.
+
+    https://sources.debian.net/src/nmh/1.6-16/debian/patches/
+    https://lintian.debian.org/full/az@debian.org.html#nmh
+
+Perhaps some nmh developer that uses Debian, or Ubuntu?, could provide
+package-building commands, including lintian(1), for Makefile.am so
+Lintian's complaints are known before release.