X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/71458b3b2492943349f7693a46792756d5013c69..8619447c9deaf234f986d645a2b4330959ab00e5:/docs/README.developers?ds=sidebyside diff --git a/docs/README.developers b/docs/README.developers index 76f650dc..eb770fc9 100644 --- a/docs/README.developers +++ b/docs/README.developers @@ -22,6 +22,15 @@ commit checklist 8. notify nmh-users? +--------------------------------- +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 +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 .c containing the code for that command @@ -147,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 ------------------------------------------------------- @@ -162,6 +179,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 +201,20 @@ 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. + 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 +224,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 +268,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 +276,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