From c5c062b01edad7c7c16417b4570446c9ba2ce683 Mon Sep 17 00:00:00 2001 From: markus schnalke Date: Fri, 7 Dec 2012 23:51:46 +0100 Subject: [PATCH] Reworked docs/README.developes to match mmh. --- docs/README.developers | 242 ++++++++++++++++++++++++------------------------ 1 file changed, 119 insertions(+), 123 deletions(-) diff --git a/docs/README.developers b/docs/README.developers index 935d0d1..e1456ff 100644 --- a/docs/README.developers +++ b/docs/README.developers @@ -2,107 +2,111 @@ # 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 and then -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 .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 - (which would contain not much else besides main()). + "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. ---- -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 =========== ================================ @@ -110,90 +114,82 @@ getpass() nmh_getpass() ------------- -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: + + + *or* (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: + + + Further more, the message should be PGP-signed. -- 1.7.10.4