One more pass at README.developers now that it's clear that my

[mmh] / docs / README.developers

diff --git a/docs/README.developers b/docs/README.developers
index ec2d243..522244a 100644 (file)
--- a/docs/README.developers
+++ b/docs/README.developers
@@ -41,12 +41,24 @@ end-users who don't have any interest in changing the configure-related files
 and don't have autoconf installed.  They'll be unable to make without playing
 around with `touch'.
 
 and don't have autoconf installed.  They'll be unable to make without playing
 around with `touch'.
 

-The correct order to commit the configure-related files is:
+The correct procedure to commit the configure-related files is:

 
 

-% cvs commit acconfig.h aclocal.m4 config.h.in configure.in configure stamp-h.in
+    % cvs commit acconfig.h aclocal.m4 configure.in
+    % autoconf && autoheader                          # or simply "make"
+    % cvs commit config.h.in configure
+    % make stamp-h.in                                 # or simply "make"
+    % cvs commit stamp-h.in

 
 

-If you haven't changed all of those files, just commit the rest in the
-stated order (e.g. cvs commit acconfig.h config.h.in stamp-h.in).
+The reason that the commits need to be split up is that the timestamps on the
+files change when the commits are done and the RCS Ids change.  If one committed
+all the files in one fell swoop (in the above relative order), timestamps would
+cause unnecessary autoconf regeneration on 'make's after the commit, which would
+waste your time and would cause your local stamp-h.in to be out-of-sync with the
+one checked into CVS (not the end of the world, but...).
+
+If you haven't changed all the files noted above, just commit the ones you have,
+in the stated order (for instance, configure.in, then configure, then
+stamp-h.in).

 
 
 -------------------
 
 
 -------------------

@@ -130,6 +142,21 @@ zotnet/tws/
     "time".  Date and time manipulation routines go here.
 
 
     "time".  Date and time manipulation routines go here.
 
 

+-------------------------------------------------------
+nmh-local functions to use in preference to OS versions
+-------------------------------------------------------
+
+For some system functions whose availability or behavior varies from OS to OS,
+nmh conditionally uses a local definition with the same name as the OS function
+(e.g. snprintf()).  For other functions, developers need to avoid the OS
+versions and always use the nmh-supplied function.  Here is a list of such
+functions: 
+
+OS function  nmh-local version to use instead
+===========  ================================
+getpass()    nmh_getpass()
+
+

 -------------
 releasing nmh
 -------------
 -------------
 releasing nmh
 -------------

@@ -150,7 +177,7 @@ account, danh, as examples here):
 
  6. Untar nmh-1.0.4.tar.gz and `diff -r' it vs. your CVS tree.  Make sure no
     files got left out of the distribution that should be in it (due to someone
 
  6. Untar nmh-1.0.4.tar.gz and `diff -r' it vs. your CVS tree.  Make sure no
     files got left out of the distribution that should be in it (due to someone

-    forgetting to update the DIST variables in the makefiles).
+    forgetting to update the DIST variables in the Makefiles).

 
  7. If you have root access on your machine, it's good at this point to do:
 
 
  7. If you have root access on your machine, it's good at this point to do:
 

@@ -163,14 +190,23 @@ account, danh, as examples here):
     making it possible for that user to Trojan the nmh code before the system
     administrator finishes installing it.
 
     making it possible for that user to Trojan the nmh code before the system
     administrator finishes installing it.
 

- 8. Preferably make an MD5 hash and/or a PGP signature of nmh-1.0.4.tar.gz.
+ 8. Make sure your new tarball uncompresses and untars with no problem.  Make
+    sure you can configure, make, and install nmh from it.
+
+ 9. If all is well and your tarball is final, go back to your CVS tree and do:
+
+    % echo 1.0.4+dev > VERSION
+
+10. Put a comment like "Upped the version number to 1.0.4+dev until the next nmh
+    release." in the ChangeLog.
+
+11. % cvs commit ChangeLog VERSION

 
 

- 9. Preferably test out the tarball, making sure you can uncompress and untar
-    it, and configure, make, install, and use nmh from it.
+12. If possible, make an MD5 hash and/or a PGP signature of nmh-1.0.4.tar.gz.

 
 

-10. % scp -p nmh-1.0.4.tar.gz* danh@mhost.com:/home/ftp/pub/nmh
+13. % scp -p nmh-1.0.4.tar.gz* danh@mhost.com:/var/ftp/pub/nmh

 
 

-11. Send an announcement to exmh-users@redhat.com, exmh-workers@redhat.com,
+14. Send an announcement to exmh-users@redhat.com, exmh-workers@redhat.com,

     mh-users@ics.uci.edu, and nmh-announce@mhost.com.  If the release fixes
     significant security holes, also send an announcement to
     bugtraq@securityfocus.com.  The exmh lists require you to be subscribed in
     mh-users@ics.uci.edu, and nmh-announce@mhost.com.  If the release fixes
     significant security holes, also send an announcement to
     bugtraq@securityfocus.com.  The exmh lists require you to be subscribed in