# # README.developers # 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. Absolute beginners should start reading docs/README.start-devel. ------------------- directory structure ------------------- 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, 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. h/ 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 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 mmh. uip/ "uip" stands for "User Interface Programs". Most mmh commands have a file in this directory named .c containing the code for that command (e.g. repl.c). In some cases there is also an auxiliary file called sbr.c which contains additional subroutines called from .c. ---------------------- version control system ---------------------- As of December 2010, nmh has switched to using git for revision control 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 http://git.marmaro.de/mmh 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 ------------- releasing mmh ------------- To make a public release of mmh (we'll use version 1.0 as example here): 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 mmh-1.0 -m 'Releasing mmh-1.0' 4. % make mmhdist 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: % chown -R 0:0 mmh-1.0 % tar cvf - mmh-1.0 | gzip -c > mmh-1.0.tar.gz 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 mmh from it. 8. If all is well and your tarball is final, go back to your workspace and do: % echo 1.0+dev > VERSION 9. % git commit VERSION; git push 10. Generate an MD5 hash and a PGP signature of the tarball: % md5sum mmh-1.0.tar.gz > mmh-1.0.tar.gz.md5sum % gpg -ab mmh-1.0.tar.gz You can verify the hash and signature with: % md5sum -c mmh-1.0.tar.gz.md5sum % gpg --verify mmh-1.0.tar.gz.asc 11. Upload the files to the web space: % scp -p mmh-1.0.tar.gz* marmaro.de:.../prog/mmh/ 12. Update the homepage. 13. Add a news item to relevant pages, e.g. freshmeat.net. 14. Send the release announcement email to the following places: *or* (bidirectional gateway) If the release fixes significant security holes, also send an announcement to bugtraq@securityfocus.com. Preferably, the announcement should contain: - the URL for the tarball - the MD5 hash - 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: Further more, the message should be PGP-signed.