5 This file is intended to provide a few tips for anyone doing development
6 on mmh. Developers who learn things "the hard way" about the mmh codebase
7 (as opposed to local info best encoded in a comment) are encouraged to
8 share their wisdom here.
10 Absolute beginners should start reading docs/README.start-devel.
17 Following is a list of mmh's directories along with a brief description
18 of the purpose of each one. Meanings are given for the abbreviations,
19 but note that these meanings are just informed guesses as to what the
20 MH developers were thinking.
23 The top-level directory. Contains files like README and INSTALL.
26 Contains utility files for the `configure' process. Ordinarily
27 nothing in here needs to be messed with, but config/config.c is
28 very interesting to have a look at.
31 Contains more specialized documentation, such as this file and
35 Contains files, file templates, and scripts to generate files that
36 will be installed in the ${prefix}/etc directory. Stuff like
40 Most of mmh's header files are kept in this central location instead
41 of in the individual source directories.
44 Contains all the input files that are processed to generate mmh's
48 "sbr" stands for "subroutine(s)". For the most part, each source
49 file in this directory contains a single function with the same
50 name as the source file. These functions are of general use and
51 are called from throughout mmh.
54 "uip" stands for "User Interface Programs". Most mmh commands have a
55 file in this directory named <command>.c containing the code for that
56 command (e.g. repl.c). In some cases there is also an auxiliary file
57 called <command>sbr.c which contains additional subroutines called
61 ----------------------
62 version control system
63 ----------------------
65 As of December 2010, nmh has switched to using git for revision control
66 instead of CVS. Mmh has stick to git. While the topic of git is beyond
67 the scope of this FAQ, to get started with git and mmh, you can run the
68 following command to checkout the mmh repository:
70 % git clone http://git.marmaro.de/mmh
72 That will create a workspace called mmh. To update that workspace
82 If you wish to change the `configure' script or its related files,
83 you'll need to first install GNU m4 and GNU autoconf. Mmh is currently
84 using a minimum of autoconf 2.61.
86 Most of the configure-related files are automatically generated. The
87 only files you should need to manually edit are `acconfig.h' and
88 `configure.ac'. Don't, for instance, edit `config.h.in'. Though it is
89 an input file from the point of view of the users (and the configure
90 script) it is an output file from the point of view of the developers
91 (and the autoconf script).
93 Note that the automatically generated autoconf files (such as
94 `config.h.in', `stamp-h.in', and `configure'), are NOT kept in the
95 version control system. Thus, when you check out the source tree,
96 you need to run the `autogen.sh' script before you can build anything:
105 To make a public release of mmh (we'll use version 1.0 as example
108 1. % echo 1.0 > VERSION
109 % date +"%Y-%m-%d" > DATE
110 (DATE should contain something like "2012-12-08")
112 2. % git commit VERSION DATE; git push
114 3. % git tag -a mmh-1.0 -m 'Releasing mmh-1.0'
118 5. Untar mmh-1.0.tar.gz and `diff -r' it vs. your workspace. Make
119 sure no files got left out of the distribution that should be in
120 it (due to someone forgetting to update the DIST variables in the
123 6. If you have root access on your machine, it's good at this point
126 % chown -R 0:0 mmh-1.0
127 % tar cvf - mmh-1.0 | gzip -c > mmh-1.0.tar.gz
129 If you leave the files in the archive as being owned by yourself,
130 your UID may coincide with one of a user on a machine where mmh is
131 being installed, making it possible for that user to Trojan the mmh
132 code before the system administrator finishes installing it.
134 7. Make sure your new tarball uncompresses and untars with no problem.
135 Make sure you can configure, make, and install mmh from it.
137 8. If all is well and your tarball is final, go back to your workspace
140 % echo 1.0+dev > VERSION
142 9. % git commit VERSION; git push
144 10. Generate an MD5 hash and a PGP signature of the tarball:
146 % md5sum mmh-1.0.tar.gz > mmh-1.0.tar.gz.md5sum
147 % gpg -ab mmh-1.0.tar.gz
149 You can verify the hash and signature with:
151 % md5sum -c mmh-1.0.tar.gz.md5sum
152 % gpg --verify mmh-1.0.tar.gz.asc
154 11. Upload the files to the web space:
156 % scp -p mmh-1.0.tar.gz* marmaro.de:.../prog/mmh/
158 12. Update the <http://marmaro.de/prog/mmh/> homepage.
160 13. Add a news item to relevant pages, e.g. freshmeat.net.
162 14. Send the release announcement email to the following places:
163 <nmh-workers@nongnu.org>
164 <nmh-announce@nongnu.org>
165 <mh-users@ics.uci.edu> *or* <comp.mail.mh> (bidirectional gateway)
167 If the release fixes significant security holes, also send an
168 announcement to bugtraq@securityfocus.com.
170 Preferably, the announcement should contain:
171 - the URL for the tarball
173 - the URL of the website
174 - a brief summary of visible changes
175 - the URL of the git diff page that shows a detailed list of
176 changes. The changes between 0.9 and 1.0 would be shown by:
177 <http://git.marmaro.de/?p=mmh;a=commitdiff;hp=mmh-0.9;h=mmh-1.0>
179 Further more, the message should be PGP-signed.