# README.developers
#
-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.
+This file is intended to provide a few tips for anyone doing development
+on mmh. Developers who learn things "the hard way" about the mmh codebase
+(as opposed to local info best encoded in a comment) are encouraged to
+share their wisdom here.
-The topics are organized alphabetically.
+Absolute beginners should start reading docs/README.start-devel.
---------------
-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 acconfig.h and configure.ac. 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
-a git tree, you need to run the autogen.sh script before you can build
-anything:
-
- % ./autogen.sh
-
-------------------
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.
+Following is a list of mmh'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.
./
The top-level directory. Contains files like README and INSTALL.
config/
- Contains utility files for the `configure' process. Ordinarily nothing in
- here needs to be messed with.
+ Contains utility files for the `configure' process. Ordinarily
+ nothing in here needs to be messed with, but config/config.c is
+ very interesting to have a look at.
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.
+ Contains files, file templates, and scripts to generate files that
+ will be installed in the ${prefix}/etc directory. Stuff like
+ replcomps.
h/
- Most of nmh's header (.h) files are kept not in the individual source
- directories, but in this central location.
+ Most of mmh's header files are kept in this central location instead
+ of in the individual source directories.
man/
- Contains all the input files that are processed to generate nmh's manual
- pages.
+ Contains all the input files that are processed to generate mmh's
+ manual pages.
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.
+ "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 mmh.
uip/
- "uip" stands for "User Interface Programs". Most nmh commands have a file
- in this directory named <command>.c containing the code for that command
- (e.g. repl.c). In some cases there is also an auxiliary file called
- <command>sbr.c which contains additional subroutines called from <command>.c
- (which would contain not much else besides main()).
+ "uip" stands for "User Interface Programs". Most mmh commands have a
+ file in this directory named <command>.c containing the code for that
+ command (e.g. repl.c). In some cases there is also an auxiliary file
+ called <command>sbr.c which contains additional subroutines called
+ from <command>.c.
----
-git
----
+----------------------
+version control system
+----------------------
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:
+instead of CVS. Mmh has stick to git. While the topic of git is beyond
+the scope of this FAQ, to get started with git and mmh, you can run the
+following command to checkout the mmh repository:
- % git clone git://git.savannah.nongnu.org/nmh.git
+ % git clone http://git.marmaro.de/mmh
-That will create a workspace called nmh. To update that workspace
-with changes to the master, cd to it and run:
+That will create a workspace called mmh. To update that workspace
+change to it and run:
% git pull
+--------------
+autoconf files
+--------------
+
+If you wish to change the `configure' script or its related files,
+you'll need to first install GNU m4 and GNU autoconf. Mmh 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 `acconfig.h' and
+`configure.ac'. 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 the
+version control system. Thus, when you check out the source tree,
+you need to run the `autogen.sh' script before you can build anything:
+
+ % ./autogen.sh
+
+
-------------------------------------------------------
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:
+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. 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
=========== ================================
-------------
-releasing nmh
+releasing mmh
-------------
-To make a public release of nmh (we'll use version 1.0.4 as examples
-here; the convention for release candidates is to use something like
-"1.0.4-RC1"):
+To make a public release of mmh (we'll use version 1.0 as example
+here):
- 1. % echo 1.0.4 > VERSION
- % date +"%e %B %Y" > DATE
- (DATE should contain something like "30 December 2000")
+ 1. % echo 1.0 > VERSION
+ % date +"%Y-%m-%d" > DATE
+ (DATE should contain something like "2012-12-08")
2. % git commit VERSION DATE; git push
- 3. % git tag -a nmh-1_0_4 -m 'Releasing nmh-1_0_4.'
+ 3. % git tag -a mmh-1.0 -m 'Releasing mmh-1.0'
- 4. % make nmhdist
+ 4. % make mmhdist
- 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
+ 5. Untar mmh-1.0.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:
+ 6. If you have root access on your machine, it's good at this point
+ to do:
- % 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
+ % chown -R 0:0 nmh-1.0
+ % tar cvf nmh-1.0.tar nmh-1.0
+ % gzip nmh-1.0.tar
- 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 leave the files in the archive as being owned by yourself,
+ your UID may coincide with one of a user on a machine where mmh is
+ being installed, making it possible for that user to Trojan the mmh
+ code before the system administrator finishes installing it.
- 7. Make sure your new tarball uncompresses and untars with no problem. Make
- sure you can configure, make, and install nmh from it.
+ 7. Make sure your new tarball uncompresses and untars with no problem.
+ Make sure you can configure, make, and install mmh from it.
- 8. If all is well and your tarball is final, go back to your workspace and do:
+ 8. If all is well and your tarball is final, go back to your workspace
+ and do:
- % echo 1.0.4+dev > VERSION
+ % echo 1.0+dev > VERSION
9. % git commit VERSION; git push
-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
+10. Generate an MD5 hash and a PGP signature of the tarball.
- You can verify the signature with
- % gpg --verify nmh-1.0.4.tar.gz.sig nmh-1.0.4.tar.gz
+ % md5sum mmh-1.0.tar.gz >mmh-1.0.tar.gz.md5sum
+ % gpg --output mmh-1.0.tar.gz.sig --detach-sig mmh-1.0.tar.gz
-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*
+ You can verify the hash and signature with:
- Then scp them across:
- % scp -p nmh-1.0.4.tar.gz* youruser@dl.sv.nongnu.org:/releases/nmh/
+ % md5sum -c mmh-1.0.tar.gz.md5sum
+ % gpg --verify mmh-1.0.tar.gz.sig mmh-1.0.tar.gz
-12. Update the http://www.nongnu.org/nmh/ homepage. (It lives in the CVS
- 'webpages repository'; see https://savannah.nongnu.org/cvs/?group=nmh)
+11. Upload the files to the web space:
-13. Add a news item to the savannah nmh page. You'll have to submit it first
- and then separately approve it (under News->Manage).
+ % scp -p mmh-1.0.tar.gz* marmaro.de:.../mmh/
-14. 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
- 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 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://git.savannah.gnu.org/cgit/nmh.git/diff/?h=nmh-1_5-release?h=nmh-1_4-release
+12. Update the http://marmaro.de/prog/mmh/ homepage.
+13. Add a news item to relevant pages, e.g. freshmeat.net.
+
+14. Send the release announcement email to the following places:
+ <nmh-workers@nongnu.org>
+ <nmh-announce@nongnu.org>
+ <mh-users@ics.uci.edu> *or* <comp.mail.mh> (bidirectional gateway)
+
+ If the release fixes significant security holes, also send an
+ announcement to bugtraq@securityfocus.com.
+
+ Preferably, the announcement should contain:
+ - the MD5 hash
+ - the URL for the tarball
+ - the URL of the website
+ - a brief summary of visible changes
+ - the URL of the git diff page that shows a detailed list of
+ changes. The changes between 0.9 and 1.0 would be shown by:
+ <http://git.marmaro.de/?p=mmh;a=commitdiff;hp=mmh-0.9;h=mmh-1.0>
+
+ Further more, the message should be PGP-signed.
projects / mmh / commitdiff