X-Git-Url: http://git.marmaro.de/?a=blobdiff_plain;f=docs%2FREADME.developers;h=a66e6e8d57e574b64d27691869a5b0b14390412e;hb=0ecdc197e9a9a4d2bb6dce395dea152fbc728b6b;hp=2946d8c1b54f5e9a44e6ff60d158deff1d8a3051;hpb=e4ccf20dcb722d8110e2a22f03e960e8f9f67898;p=mmh diff --git a/docs/README.developers b/docs/README.developers index 2946d8c..a66e6e8 100644 --- a/docs/README.developers +++ b/docs/README.developers @@ -6,26 +6,50 @@ This file is intended to provide a few tips for anyone doing development on nmh. 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 and then -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 , then GNU autoconf +() and 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: @@ -125,73 +149,55 @@ getpass() nmh_getpass() 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