Developers who learn things "the hard way" about the nmh codebase (as opposed to
local info best encoded in a comment) are encouraged to share their wisdom here.
-The topics are organized alphabetically.
-
-
---------------
-autoconf files
---------------
-
-If you wish to change the `configure' script or its related files, you'll need
-to first install GNU m4, available from <ftp://ftp.gnu.org/pub/gnu/m4/> and then
-GNU autoconf (<ftp://ftp.gnu.org/pub/gnu/autoconf/>). Nmh is currently using
-a minimum of autoconf 2.61.
-
-Most of the configure-related files are automatically generated. The only files
-you should need to manually edit are configure.ac and aclocal.m4. Don't, for
-instance, edit config.h.in. Though it is an input file from the point of view
-of the users (and the configure script) it is an output file from the point of
-view of the developers (and the autoconf script).
-
-Note that the automatically generated autoconf files (such as config.h.in,
-stamp-h.in, and configure), are NOT kept in git. Thus, when you check out
+Following a commit checklist, the topics are organized alphabetically.
+
+----------------
+commit checklist
+----------------
+
+1. code updated?
+2. test added?
+3. make distcheck passed?
+4. man page and other documentation updated?
+5. docs/pending-release-notes updated?
+6. should commit message reference bug report?
+7. update/close bug report (with commit id)?
+8. notify nmh-users?
+
+
+-------------------------
+autoconf & automake files
+-------------------------
+
+If you wish to change the `configure' script, the generated Makefile
+or other related files, you'll need to first install GNU m4, available
+from <ftp://ftp.gnu.org/pub/gnu/m4/>, then GNU autoconf
+(<ftp://ftp.gnu.org/pub/gnu/autoconf/>) and GNU automake
+(<ftp://ftp.gnu.org/pub/gnu/automake/>). Nmh is currently using a
+minimum of autoconf 2.61 and automake 1.10.
+
+Most of the configure-related files are automatically generated.
+The only files you should need to manually edit are configure.ac
+and any autoconf macros in the m4 directory. Don't, for instance,
+edit config.h.in. Though it is an input file from the point of
+view of the users (and the configure script) it is an output file
+from the point of view of the developers (and the autoconf script).
+
+If you wish to add a new autoconf macro, it should be placed in it's
+own file and put in the m4 directory; aclocal will automatically pick
+it up and automake will add it to the distribution target automatically.
+
+If you wish to make changes to the Makefile, you will need to edit
+Makefile.am. See the automake documentation if you need further help.
+You should always check changes to Makefile.am by using "make distcheck".
+
+Note that the automatically generated autotools files (such as config.h.in,
+Makefile.in, and configure), are NOT kept in git. Thus, when you check out
a git tree, you need to run the autogen.sh script before you can build
anything:
releasing nmh
-------------
-To make a public release of nmh (we'll use version 1.0.4 and my mhost.com
-account, danh, as examples here; the convention for release candidates
-is to use something like "1.0.4-RC1"):
+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.0.4 > VERSION
+ 1. % 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 tag -a nmh-1_0_4 -m 'Releasing nmh-1_0_4.'
-
- 4. % make nmhdist
-
- 5. Untar nmh-1.0.4.tar.gz and `diff -r' it vs. your workspace. 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).
-
- 6. If you have root access on your machine, it's good at this point to do:
+ 3. % git tag -a 1.5 -m 'Releasing nmh-1.5.'
- % chown -R 0:0 nmh-1.0.4
- % tar cvf nmh-1.0.4.tar nmh-1.0.4
- % gzip nmh-1.0.4.tar
+ Note that the new convention for tagging is to simply tag with the
+ version number (tag formats in the past have varied).
- If you leave the files in the archive as being owned by yourself, your UID
- may coincide with one of a user on a machine where nmh is being installed,
- making it possible for that user to Trojan the nmh code before the system
- administrator finishes installing it.
+ 4. % make distcheck
- 7. Make sure your new tarball uncompresses and untars with no problem. Make
- sure you can configure, make, and install nmh from it.
+ If you want to check the distribution build with some particular
+ configure options, set the DISTCHECK_CONFIGURE_FLAGS variable.
+ E.g.:
- 8. If all is well and your tarball is final, go back to your workspace and do:
+ % make distcheck DISTCHECK_CONFIGURE_FLAGS=--with-cyrus-sasl
- % echo 1.0.4+dev > VERSION
+ 5. If all is well and your tarball is final, go back to your workspace and do:
- 9. % git commit VERSION; git push
+ % echo 1.5+dev > VERSION
-10. If possible, make an MD5 hash and/or a PGP signature of nmh-1.0.4.tar.gz.
- Assuming you have gpg set up, this should be:
- % gpg --output nmh-1.0.4.tar.gz.sig --detach-sig nmh-1.0.4.tar.gz
+ 6. % git commit VERSION; git push
- You can verify the signature with
- % gpg --verify nmh-1.0.4.tar.gz.sig nmh-1.0.4.tar.gz
+ 7. Upload the distribution file to savannah. You can automate this process
+ by doing:
-11. Upload the files to savannah. First make sure they are mode 664 so
- they will have the right permissions on the server end
- (see https://savannah.gnu.org/maintenance/SharedDownloadArea)
- % chmod 664 nmh-1.0.4.tar.gz*
+ % make upload SAVANNAH_USERNAME=username
- Then scp them across:
- % scp -p nmh-1.0.4.tar.gz* youruser@dl.sv.nongnu.org:/releases/nmh/
+ This will automatically call gpg to sign the release. You can bypass
+ this step by setting the SKIP_GPG_SIG variable.
-12. Update the http://www.nongnu.org/nmh/ homepage. (It lives in the CVS
+ 8. Update the http://www.nongnu.org/nmh/ homepage. (It lives in the CVS
'webpages repository'; see https://savannah.nongnu.org/cvs/?group=nmh)
-13. Add a news item to the savannah nmh page. You'll have to submit it first
+ 9. Add a news item to the savannah nmh page. You'll have to submit it first
and then separately approve it (under News->Manage).
-14. Send the release announcement email to the following places:
+10. Send the release announcement email to the following places:
nmh-workers@nongnu.org
nmh-announce@nongnu.org
exmh-users@redhat.com
exmh-workers@redhat.com
mh-e-users@lists.sourceforge.net
- mh-users@ics.uci.edu *or* comp.mail.mh (there is a bidirectional gateway)
If the release fixes significant security holes, also send an announcement
to bugtraq@securityfocus.com. The exmh lists require you to be subscribed
projects / mmh / blobdiff