X-Git-Url: http://git.marmaro.de/?a=blobdiff_plain;f=docs%2FREADME.developers;h=a66e6e8d57e574b64d27691869a5b0b14390412e;hb=ac99d23ec89df5e72b39c7ae950c084ca0377eca;hp=4437340fbe511916eca9ce77b1f47ef611c43582;hpb=1a8f78d12723e301661fd469f39fb6a62bb10954;p=mmh
diff --git a/docs/README.developers b/docs/README.developers
index 4437340..a66e6e8 100644
--- a/docs/README.developers
+++ b/docs/README.developers
@@ -1,52 +1,59 @@
#
# 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?
---------------
-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 ().
+-------------------------
+autoconf & automake files
+-------------------------
-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 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.
-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.
+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).
-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 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.
-The correct order to commit the configure-related files is:
+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".
- % cvs commit acconfig.h config.h.in configure.in configure stamp-h.in
+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:
-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).
+ % ./autogen.sh
-------------------
@@ -56,7 +63,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.
@@ -65,6 +72,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.
@@ -81,14 +92,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.
@@ -97,7 +100,10 @@ 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.
+
+test/
+ The num unit test suite.
uip/
"uip" stands for "User Interface Programs". Most nmh commands have a file
@@ -106,67 +112,105 @@ 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:
+
+ % git clone git://git.savannah.nongnu.org/nmh.git
+
+That will create a workspace call nmh. To update that workspace
+with changes to the master, cd to it and run:
+
+ % git pull
-zotnet/mf/
- "mf" stands for "Mail Filter". The filtering in this case apparently refers
- to translation between different address and mailbox formats.
-zotnet/mts/
- MTS code not specific to any single MTS apparently goes here.
+-------------------------------------------------------
+nmh-local functions to use in preference to OS versions
+-------------------------------------------------------
-zotnet/tws/
- No idea what "tws" stands for, other than 't' almost certainly standing for
- "time". Date and time manipulation routines go here.
+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
-------------
-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. % 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 1.5 -m 'Releasing nmh-1.5.'
+
+ Note that the new convention for tagging is to simply tag with the
+ version number (tag formats in the past have varied).
+
+ 4. % make distcheck
+
+ If you want to check the distribution build with some particular
+ configure options, set the DISTCHECK_CONFIGURE_FLAGS variable.
+ E.g.:
+
+ % make distcheck DISTCHECK_CONFIGURE_FLAGS=--with-cyrus-sasl
+
+ 5. If all is well and your tarball is final, go back to your workspace and do:
-1. % echo 1.0.4 > VERSION
+ % echo 1.5+dev > VERSION
-2. Put a comment like "Released nmh-1.0.4." in the ChangeLog.
+ 6. % git commit VERSION; git push
-3. % cvs commit ChangeLog VERSION
+ 7. Upload the distribution file to savannah. You can automate this process
+ by doing:
-4. % cvs tag nmh-1_0_4
- (cvs treats dots specially, so underscores are substituted here.)
+ % make upload SAVANNAH_USERNAME=username
-5. % make nmhdist
+ This will automatically call gpg to sign the release. You can bypass
+ this step by setting the SKIP_GPG_SIG variable.
-6. Preferably make an MD5 hash and/or a PGP signature of nmh-1.0.4.tar.gz.
+ 8. Update the http://www.nongnu.org/nmh/ homepage. (It lives in the CVS
+ 'webpages repository'; see https://savannah.nongnu.org/cvs/?group=nmh)
-7. Preferably test out the tarball, making sure you can uncompress and untar it,
- and configure, make, install, and use nmh from it.
+ 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).
-8. % scp -p nmh-1.0.4.tar.gz* your-uid@mhost.com:/home/ftp/pub/nmh
+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
-9. 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. None of these lists require you to be subscribed
- 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 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:
+ Preferably, the announcement should contain the MD5 hash generated above,
+ 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 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