Last pass at README.developers -- Kimmo's 5-step commit was overkill. You only

[mmh] / docs / README.developers

diff --git a/docs/README.developers b/docs/README.developers
index ec2d243..9edd701 100644 (file)
--- a/docs/README.developers
+++ b/docs/README.developers
@@ -41,12 +41,23 @@ 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
+    % autoheader; autoconf; date > stamp-h.in
+    % cvs commit config.h.in configure 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 for the three-step commit is that configure.in contains the RCS $Id
+keyword, so when you commit it, a new version is written locally.  Therefore,
+the autoconf regeneration should be held off until after the commit, or your
+local stamp-h.in will become out-of-sync with the CVS version (granted, not that
+big a deal).  For the second step, you're doing the same commands as a 
+`make reset' would do, but using that command would require extra configure runs
+to make Makefile be up-to-date.
+
+If you haven't changed all the files noted above, just commit the ones you have
+changed, in the stated order (for instance, configure.in, then configure and
+stamp-h.in).

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

@@ -130,6 +141,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 +176,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 +189,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