Reworked BUGS section of nmh(7) man page, and added excerpt

[nmh] / docs / README.developers

diff --git a/docs/README.developers b/docs/README.developers
index 8b9ecdf0ece3f4ad7e7511f6bec37fef4b551c1e..f0f05c8250158726ae4656cbb612d401cae93aa6 100644 (file)
--- a/docs/README.developers
+++ b/docs/README.developers
@@ -111,9 +111,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 +163,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 +201,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 +233,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 +259,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).