X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/d3df81fcf2e52e4e484da1c1df431c7a915a3139..c525020c77134b8832587755b7c05764a0516d80:/docs/README.developers diff --git a/docs/README.developers b/docs/README.developers index b243b5d3..692f352b 100644 --- a/docs/README.developers +++ b/docs/README.developers @@ -1,60 +1,73 @@ # # README.developers # -# $Id$ -# 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. +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? + +A buildbot at http://orthanc.ca:8010/waterfall polls for new commits and +builds them on a few platforms. Keep an eye on its progress in case +you've committed something non-portable. (If you can provide another +platform, contact the nmh-workers list.) --------------- -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 (). +--------------------------------- +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). -Most of the configure-related files are automatically generated. The only files -you should need to manually edit are acconfig.h and configure.in. 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 do change acconfig.h or configure.in and want to `cvs commit' them, be -sure to regenerate the output files and commit them as well. The easiest way to -regenerate the files is to simply run `make' -- it'll do the necessary calls of -autoconf and autoheader and will do a `./config.status --recheck', which will -exercise your new configure script. +------------------------- +autoconf & automake files +------------------------- -When you commit the configure-related files, it's very important to commit them -in the right order. The timestamps on the files in the CVS archive are based on -the current time at the moment they were committed -- the timestamps from the -local files you commit are not copied over. If you commit the files in the -wrong order, you'll cause unnecessary calls of `autoconf' to occur when people -try to `make' their copies of the latest CVS source. These people may be -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'. +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.68 and automake 1.12. -The correct procedure to commit the configure-related files is: +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). - % cvs commit acconfig.h aclocal.m4 configure.in - % autoconf && autoheader - % cvs commit config.h.in configure - % make stamp-h.in - % cvs commit stamp-h.in +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 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 sequence is the RCS Id strings in the edited files -- they change when -you commit the changes. +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". -You can run just "make" instead of the other commands in between cvs commits. +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: + + % ./autogen.sh ------------------- @@ -64,7 +77,7 @@ directory structure Following is a list of nmh's directories along with a brief description of the purpose of each one. Meanings are given for the abbreviations, but note that these meanings are just informed guesses as to what the MH developers were -thinking. +thinking. ./ The top-level directory. Contains files like README and INSTALL. @@ -73,6 +86,10 @@ config/ Contains utility files for the `configure' process. Ordinarily nothing in here needs to be messed with. +docs/ + Contains more specialized documentation, such as this file and + the FAQ. + etc/ Contains files, file templates, and scripts to generate files that will be installed in the ${prefix}/etc directory. Stuff like replcomps. @@ -89,14 +106,6 @@ mts/ "mts" stands for "Message Transfer Service". Source files specific to the different MTSs go in the subdirectories. -mts/mmdf/ - "mmdf" stands for "Multichannel Memorandum Distribution Facility". It is an - alternative to sendmail used primarily on SCO UNIX. - -mts/sendmail/ - When nmh is configured --with-mts=sendmail, the files in this directory are - used. - mts/smtp/ When nmh is configured to just talk to an SMTP server over TCP/IP, the source in this directory is compiled. @@ -105,7 +114,17 @@ sbr/ "sbr" stands for "subroutine(s)". For the most part, each source file in this directory contains a single function with the same name as the source file. These functions are of general use and are called from throughout - nmh. + nmh. + +SPECS/ + Contains files such as RPM specs. + +test/ + The num unit test suite. + +tools/ + "tools" contains tools, scripts, and supporting files used by the + developers while writing, debugging, and testing the code. uip/ "uip" stands for "User Interface Programs". Most nmh commands have a file @@ -114,28 +133,40 @@ uip/ sbr.c which contains additional subroutines called from .c (which would contain not much else besides main()). -zotnet/ - Files in this hierarchy were either written by or moved here by UCI - (University of California, Irvine) after they took over MH from the Rand - Corporation. "Zot!" is the sound effect made by the anteater in the "B.C." - comic strip when its tongue lashes out at ants. The anteater is UCI's - official mascot. Not sure whether UCInet was once called ZotNet... -zotnet/bboards/ - UCI added Bulletin Board functionality to MH with the `bbc' command. This - functionality has been removed from nmh but apparently files in this - directory are still needed for other purposes. +--- +git +--- + +As of December 2010, nmh has switched to using git for revision control +instead of CVS. While the topic of git is beyond the scope of this FAQ, +to get started with git & nmh, you can run the following command to checkout +the nmh repository (with read-only access to it): + + % git clone git://git.savannah.nongnu.org/nmh.git + +That will create a workspace called nmh. To update that workspace +with changes to the master, cd to it and run: -zotnet/mf/ - "mf" stands for "Mail Filter". The filtering in this case apparently refers - to translation between different address and mailbox formats. + % git pull -zotnet/mts/ - MTS code not specific to any single MTS apparently goes here. +If you are a project member and want write access to the repository, +you'll have to checkout with the following command instead of the one +above: -zotnet/tws/ - No idea what "tws" stands for, other than 't' almost certainly standing for - "time". Date and time manipulation routines go here. + % git clone @git.sv.nongnu.org:/srv/git/nmh.git + +We suggest using git pull --rebase instead of the default merge for +git pull. If you don't want to add the --rebase option every time, +you can tell git pull to always rebase in your nmh workspace by +cd'ing to it and running the following command: + + % git config --bool branch.master.rebase true + +And you'll probably want the following, also, so that --rebase applies +to any new branches that you create: + + % git config branch.autosetuprebase always ------------------------------------------------------- @@ -146,74 +177,139 @@ 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: +functions: 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 +-------------- + +The nmh test suite is run through the Makefile, with "make check" +or "make distcheck". + +In the nmh test suite, nmh programs to be tested should be invoked +through the run_test or run_prog shell functions defined in +test/common.sh. + +Instead of echoing test progress, use start_test()/finish_test() +from tests/common.sh. These will report the particular test name, +within the test, only if there is a failure. + +To enable the use of valgrind, where available, set the environment +variable NMH_VALGRIND to a non-null value. However, a separate +environment variable, VALGRIND_ME, triggers the use of valgrind in +test/inc/test-eom-align because it greatly extends the duration of +that test. + +If valgrind complains about "serious error when reading debuginfo" +from a library, either update or remove the debuginfo package for +the offending library. + + ------------- 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): +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. Create a release branch. The convention is to name release branches + with the name "-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 - 1. % echo 1.0.4 > VERSION + Then do: - 2. Put a comment like "Released nmh-1.0.4." in the ChangeLog. + % git checkout 1.5-release - 3. % cvs commit ChangeLog VERSION + You are now on the 1.5 release branch. - 4. % cvs tag nmh-1_0_4 - (cvs treats dots specially, so underscores are substituted here.) + 2. % echo 1.5 > VERSION + % date +"%e %B %Y" > DATE + (DATE should contain something like "30 December 2000") - 5. % make nmhdist + 3. % git commit VERSION DATE; git push - 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). + 4. % git tag -a 1.5 -m 'Releasing nmh-1.5.' + % git push --tags - 7. If you have root access on your machine, it's good at this point to do: + Note that the new convention for tagging is to simply tag with the + version number (tag formats in the past have varied). - % 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 + 5. % make distcheck - 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. + If you want to check the distribution build with some particular + configure options, set the DISTCHECK_CONFIGURE_FLAGS variable. + E.g.: - 8. Make sure your new tarball uncompresses and untars with no problem. Make - sure you can configure, make, and install nmh from it. + % make distcheck DISTCHECK_CONFIGURE_FLAGS=--with-cyrus-sasl - 9. If all is well and your tarball is final, go back to your CVS tree and do: + 6. Upload the distribution file to savannah. You can automate this process + by doing: - % echo 1.0.4+dev > VERSION + % make upload SAVANNAH_USERNAME=username -10. Put a comment like "Upped the version number to 1.0.4+dev until the next nmh - release." in the ChangeLog. + This will automatically call gpg to sign the release. You can bypass + this step by setting the SKIP_GPG_SIG variable. -11. % cvs commit ChangeLog VERSION + 7. Update the http://www.nongnu.org/nmh/ homepage. (It lives in the CVS + 'webpages repository'; see https://savannah.nongnu.org/cvs/?group=nmh) -12. If possible, make an MD5 hash and/or a PGP signature of nmh-1.0.4.tar.gz. + 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). -13. % scp -p nmh-1.0.4.tar.gz* danh@mhost.com:/var/ftp/pub/nmh + 9. 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 -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 - order to post. Note that you don't need to post separately to comp.mail.mh, - as the mh-users mailing list is apparently bidirectionally gatewayed to it. + If the release fixes significant security holes, also send an announcement + to bugtraq@securityfocus.com. The exmh lists require you to be subscribed + in order to post. Note that you don't need to post separately to + comp.mail.mh, as the mh-users mailing list is apparently bidirectionally + gatewayed to it. Preferably, the announcement should contain the MD5 hash generated above, - and should be PGP-signed. It should include the FTP URL for the tarball as + and should be PGP-signed. It should include the URL for the tarball as well as the URL of the website. It should contain a brief summary of - visible changes, as well as the URL of the cvsweb diff page that would show - a detailed list of changes. The changes between 1.0.3 and 1.0.4 would be - shown by: + visible changes, as well as the URL of the git diff page that would show + a detailed list of changes. The changes between 1.5 and 1.4 would be + shown by [this is just a guess, I don't know anything about cgit, and + it assumes that we tag with nmh-x_x-release from now on]: - http://www.mhost.com/cgi-bin/cvsweb/nmh/ChangeLog?r1=1.40&r2=1.71 + http://git.savannah.gnu.org/cgit/nmh.git/diff/?h=nmh-1_5-release?h=nmh-1_4-release