X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/71458b3b2492943349f7693a46792756d5013c69..51919715ad7a57f2c74854a6d3d6374578f46985:/docs/README.developers

diff --git a/docs/README.developers b/docs/README.developers
index 76f650dc..ec0b29d7 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
 -------------------------
@@ -162,6 +171,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
 --------------
@@ -187,18 +211,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 "<version>-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 +255,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 +263,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