X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/71458b3b2492943349f7693a46792756d5013c69..00c626ff05455c94d926c31371ea966abf7abc1e:/docs/README.developers?ds=sidebyside diff --git a/docs/README.developers b/docs/README.developers index 76f650dc..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,6 +22,21 @@ 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). +* Use done() instead of _exit(3) except after a fork(3). + ------------------------- autoconf & automake files @@ -102,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 .c containing the code for that command @@ -147,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 ------------------------------------------------------- @@ -162,6 +186,21 @@ OS function nmh-local version to use instead getpass() nmh_getpass() +------------------- +nmh temporary files +------------------- + +To create a temporary file, use m_mktemp2() or m_mktemp(). They use +mkstemp(3), but they also register the temporary file for removal on +program termination. So, do not use mkstemp() directly. + +To further support this, nmh_init() must be called at the beginning of +main(). And, if a child process is not going to immediately call one +of the exec(3) functions or _exit(3) after a fork(3), it should call +unregister_for_removal(0). Finally, nmh_init() sets up signal handlers +for several signals: these signal handlers should not be disabled. + + -------------- nmh test suite -------------- @@ -169,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 @@ -187,18 +235,43 @@ To make a public release of nmh (we'll use version 1.5 as the example here; the convention for release candidates is to use something like "1.5-RC1"): - 1. % echo 1.5 > VERSION + 1. Create a release branch. The convention is to name release branches + with the name "-release". + + % git branch 1.5-release + + 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 push --tags + + Then do: + + % git checkout 1.5-release + + You are now on the 1.5 release branch. + + 2. % echo 1.5 > VERSION % date +"%e %B %Y" > DATE (DATE should contain something like "30 December 2000") - 2. % git commit VERSION DATE; git push + 3. % git commit VERSION DATE; git push - 3. % git tag -a 1.5 -m 'Releasing nmh-1.5.' + 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). - 4. % make distcheck + 5. % make distcheck If you want to check the distribution build with some particular configure options, set the DISTCHECK_CONFIGURE_FLAGS variable. @@ -206,13 +279,7 @@ here; the convention for release candidates is to use something like % make distcheck DISTCHECK_CONFIGURE_FLAGS=--with-cyrus-sasl - 5. If all is well and your tarball is final, go back to your workspace and do: - - % echo 1.5+dev > VERSION - - 6. % git commit VERSION; git push - - 7. Upload the distribution file to savannah. You can automate this process + 6. Upload the distribution file to savannah. You can automate this process by doing: % make upload SAVANNAH_USERNAME=username @@ -220,13 +287,13 @@ here; the convention for release candidates is to use something like This will automatically call gpg to sign the release. You can bypass this step by setting the SKIP_GPG_SIG variable. - 8. Update the http://www.nongnu.org/nmh/ homepage. (It lives in the CVS + 7. Update the http://www.nongnu.org/nmh/ homepage. (It lives in the CVS 'webpages repository'; see https://savannah.nongnu.org/cvs/?group=nmh) - 9. Add a news item to the savannah nmh page. You'll have to submit it first + 8. Add a news item to the savannah nmh page. You'll have to submit it first and then separately approve it (under News->Manage). -10. Send the release announcement email to the following places: + 9. Send the release announcement email to the following places: nmh-workers@nongnu.org nmh-announce@nongnu.org exmh-users@redhat.com @@ -248,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.