[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Changes to HACKING
From: |
Eric Blake |
Subject: |
Changes to HACKING |
Date: |
Tue, 22 Aug 2006 16:16:53 +0000 |
CVSROOT: /sources/m4
Module name: m4
Changes by: Eric Blake <ericb> 06/08/22 16:16:48
Index: HACKING
===================================================================
RCS file: HACKING
diff -N HACKING
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ HACKING 22 Aug 2006 16:16:47 -0000 1.2
@@ -0,0 +1,421 @@
+GNU M4
+******
+
+1. Introduction
+===============
+
+This file attempts to describe the processes we use to maintain M4,
+and is not part of a release distribution.
+
+
+2. Maintenance Notes
+====================
+
+* If you incorporate a change from somebody on the net:
+ If it is a large change, you must make sure they have signed the
+ appropriate paperwork, and be sure to add their name and email
+ address to THANKS. AUTHORS is built from the FSF list of copyright
+ assignments, on fencepost.gnu.org.
+
+* If somebody reports a new bug, write a test case, then mention his
+ name in the ChangeLog entry.
+
+* The correct response to most actual bugs is to write a new test case
+ which demonstrates the bug. Then fix the bug, re-run the test suite,
+ and check everything in.
+
+* Changes with user-visible effects must be mentioned in NEWS.
+
+* GNU Coding Standards should be followed:
+ http://www.gnu.org/prep/standards/
+ Additionally, while GNU M4 is not yet POSIX compliant, we are trying
+ to get closer to it (although some design decisions state that POSIX
+ compliance should only happen when POSIXLY_CORRECT is in the
+ environment or the -G option was passed on the command line):
+ http://www.opengroup.org/onlinepubs/009695399/utilities/m4.html
+
+
+3. Bootstrapping
+================
+
+* Before you can build from CVS, you need to bootstrap. This requires a
+ pre-installed version of GNU M4 1.4.x or later, built from a package,
+ Autoconf 2.60 or later, Automake 1.9b or later, CVS Head of Libtool
+ (will become Libtool 2.0), Gettext 0.15 or later, and a CVS checkout
+ of gnulib. Gnulib can be obtained by:
+ cvs -z3 -d:pserver:address@hidden:/sources/gnulib co gnulib
+
+* Either add the gnulib directory to your PATH, or run
+ GNULIB_TOOL=path/to/gnulib/gnulib-tool ./bootstrap
+
+* When it is time for a release, it is a good idea to bootstrap with
+ official releases of the autotools, rather than CVS builds, to reduce
+ the pain of a user re-running bootstrap on the packaged M4. However,
+ files installed by Automake should be updated to the latest version
+ from their respective upstream source, rather than the version that
+ shipped with the automake release.
+
+
+4. Test Suite
+=============
+
+* Use
+ make check
+ liberally, on as many platforms as you can. Use as many compilers and
+ linkers you can.
+
+* Some of the testsuite is generated from the documentation.
+ All instances of @example in doc/m4.texinfo that are not preceeded by
+ "@comment ignore" are turned into tests in the tests directory.
+
+
+5. Editing 'ChangeLog'
+======================
+
+* When in doubt, check that emacs can syntax-color properly in
+ change-log-mode. And preferably use emacs 'C-x 4 a'
+ (add-change-log-entry-other-window) to open ChangeLog with an
+ appropriate new template.
+
+* If this change is by a different author, or on a different date to the
+ last entry start a new entry at the top of the file with the format
+ (note two spaces between each field):
+
+yyyy-mm-dd Name of Author <address@hidden>
+
+* If more than one person collaborated on the change, additional
+ authors can be listed on subsequent lines, thus:
+
+yyyy-mm-dd Name of Main Author <address@hidden>,
+ Name of Contributor <address@hidden>
+
+* Where a change author did not supply a copyright assignment, but the
+ changes they submitted were sufficiently trivial to commit in any case
+ (see the GCS for guidelines on this), then flag this against their
+ name in the header, thus:
+
+yyyy-mm-dd Name of Author <address@hidden> (tiny change)
+
+* Preferably the next part should be a description of the overall
+ purpose of the change, separated from the header by a blank line,
+ indented by 1 tab, and filled at column 72. The last character of the
+ description should be a colon, :.
+
+* Changes to each file come next. Each new file starts on a new line,
+ indented by 1 tab and starting with an asterisk and a space. Multiple
+ files can be listed here relative to $top_srcdir, and comma separated.
+ Names of functions (or sections as appropriate) to which the change
+ applies should be named inside parentheses and comma separated. If
+ this goes beyond column 72, then parens should be closed and re-opened
+ on the next line:
+
+ * file, another/file, test/testcases/foo.test (func_foo)
+ (func_bar, func_baz): Description of changes.
+
+* If the change does not apply to particular functions (or sections),
+ the section list can be omitted:
+
+ * file, another/file, test/testcases/foo.test: General changes.
+
+* If the changes are particular to certain architectures, they should be
+ listed after the functions in square brackets:
+
+ * file, another/file (func_foo) [linux, solaris]: Description of
+ changes.
+
+* Subsequent changes in other files that are related to the same overall
+ enhancement or bugfix should be listed concurrently, without blank
+ lines. Always start a fresh line for a new file:
+
+ * file, another/file (func_foo) [linux, solaris]: Description of
+ changes.
+ * doc/foo.texi (Invoking Foo): Document.
+ * NEWS: Updated.
+
+* If the change is in response to a problem reported by someone other
+ than the author, then credit them at the end of the description with:
+
+ Reported by Reporter Name <address@hidden>.
+
+* See the GNU Coding Standards document for more details on ChangeLog
+ formatting.
+
+
+6. Release Procedure
+====================
+
+* If you are an m4 maintainer, but have not yet registered your
+ gpg public key and (preferred) email address with the FSF, send an
+ email, preferably GPG-signed, to <address@hidden> that includes
+ the following:
+
+ (a) name of package(s) that you are the maintainer for, and your
+ preferred email address.
+
+ (b) an ASCII armored copy of your GnuPG key, as an attachment.
+ ("gpg --export -a YOUR_KEY_ID > mykey.asc" should give you
+ this.)
+
+ When you have received acknowledgement of your message, the proper GPG
+ keys will be registered on ftp-upload.gnu.org and only then will you be
+ authorized to upload files to the FSF ftp machines.
+
+* If you do not have access to the mailing list administrative interface,
+ approach the list owners for the password. Be sure to check the lists
+ (esp. bug-m4) for outstanding bug reports also in the list of
+ pending moderation requests. This step is not strictly necessary.
+
+* Make sure you have wget installed.
+
+* Make sure you have a copy of xdelta installed, and a copy of the previous
+ release tarball in the build directory.
+
+* Make sure your locale is sane, e.g. by exporting LC_ALL=C.
+
+* Update the version number in configure.ac.
+ See http://www.gnu.org/software/libtool/contribute.html for details of
+ the numbering scheme (m4 uses the same scheme as libtool).
+
+* Update NEWS, ChangeLog.
+
+* Run ./bootstrap.
+
+* Run ./configure (or create a build directory first and run configure
+ from there, if you want to keep the build tree separate).
+
+* Run `make -fMakefile.maint fetch' (or `make -f../Makefile.maint fetch'
+ if you are running from a VPATH build directory, where `../' is the
+ relative path to the directory with `configure' in it), which will
+ fetch new versions of the files that are maintained outside of m4. If
+ you are using GNU make, the included GNUmakefile allows you to leave
+ off the '-fMakefile.maint'.
+
+* Run `make distcheck'. If there are any problems, fix them and start
+ again.
+
+* Run ./commit from the source tree.
+
+* Run `make -fMakefile.maint cvs-dist' (or `make -f../Makefile.maint
+ cvs-dist' if you are running from a VPATH build directory, where `../'
+ is the relative path to the directory with `configure' in it), which
+ will build a release tarball (with `make distcheck'), tag the tree
+ with release-$(VERSION) and generate the gpg signature files.
+
+* Run 'make -f[../]Makefile.maint deltas' (pass
+ LASTRELEASE=maj.min[.mic[alpha]] if needed) to create both diff and
+ xdelta files between the previous release tarball and the new with
+ detached gpg signature files and clear signed directive files.
+
+* Upload release tarball, diff file and xdelta file, plus their associated
+ detached gpg signature files and clear signed directive files to
+ ftp-upload.gnu.org. If the upload is destined for ftp.gnu.org, then the
+ files should be placed in the /incoming/ftp directory. If the upload is
+ an alpha release destined for alpha.gnu.org, then the files should be
+ placed in the /incoming/alpha directory.
+
+* Send announcement to address@hidden, address@hidden, and
+ address@hidden If not an alpha send to address@hidden
+ as well.
+
+* Update version number in configure.ac to next alpha number.
+ See http://www.gnu.org/software/libtool/contribute.html for details of
+ the numbering scheme.
+
+* Update NEWS, ChangeLog.
+
+* Run ./commit.
+
+* For non-alpha releases, update the webpages. Replace manual.html with
+ the new one (generate with `make -f[../]Makefile.maint web-manual').
+
+
+7. Alpha release note template
+==============================
+
+To: address@hidden, address@hidden, address@hidden
+Subject: GNU M4 @VERSION@ released (alpha release).
+
+The GNU M4 Team is pleased to announce alpha release @VERSION@ of GNU
+M4.
+
+GNU `m4' is an implementation of the traditional Unix macro processor.
+It is mostly SVR4 compatible, although it has some extensions (for
+example, handling more than 9 positional parameters to macros). `m4'
+also has built-in functions for including files, running shell commands,
+doing arithmetic, etc. Autoconf needs GNU `m4' for generating
+`configure' scripts, but not for running them.
+
+Here are the compressed sources:
+
+ ftp://alpha.gnu.org/gnu/m4/address@hidden@.tar.gz address@hidden@]
+ ftp://alpha.gnu.org/gnu/m4/address@hidden@.tar.bz2 address@hidden@]
+
+Here are the xdeltas and diffs against address@hidden@:
+
+ ftp://alpha.gnu.org/gnu/m4/address@hidden@address@hidden@.diff.gz
address@hidden@]
+ ftp://alpha.gnu.org/gnu/m4/address@hidden@address@hidden@.xdelta
address@hidden@]
+
+Here are the gpg detached signatures:
+
+ ftp://alpha.gnu.org/gnu/m4/address@hidden@.tar.gz.sig
+ ftp://alpha.gnu.org/gnu/m4/address@hidden@.tar.bz2.sig
+ ftp://alpha.gnu.org/gnu/m4/address@hidden@address@hidden@.diff.gz.sig
+ ftp://alpha.gnu.org/gnu/m4/address@hidden@address@hidden@.xdelta.sig
+
+You should download the signature named after any tarball you download,
+and then verify its integrity with, for example:
+
+ gpg --verify address@hidden@.tar.gz.sig
+
+If that command fails because you don't have the required public key,
+then run this command to import it:
+
+ gpg --keyserver wwwkeys.pgp.net --recv-keys @KEY@
+
+Here are the MD5 and SHA1 checksums:
+
+ @MD5SUM@ address@hidden@.tar.gz
+ @MD5SUM@ address@hidden@.tar.bz2
+ @MD5SUM@ address@hidden@address@hidden@.diff.gz
+ @MD5SUM@ address@hidden@address@hidden@.xdelta
+ @SHA1SUM@ address@hidden@.tar.gz
+ @SHA1SUM@ address@hidden@.tar.bz2
+ @SHA1SUM@ address@hidden@address@hidden@.diff.gz
+ @SHA1SUM@ address@hidden@address@hidden@.xdelta
+
+This release has @address@hidden
+
+This release was bootstrapped with @address@hidden
+
+Alternatively, you can fetch the unbootstrapped sourcecode from
+anonymous cvs by using the following commands:
+
+ $ export CVS_RSH=ssh
+ $ cvs -z3 -d :pserver:address@hidden:/sources/m4 \
+ co -r @CVS_RELEASE_TAG@ m4
+
+You will then need to have recent versions of Automake and Autoconf
+installed, and a recent checkout of gnulib, in order to bootstrap the
+checked out sources yourself.
+
+New in @VERSION@: @RELEASE_DATE@
+
+ @EXCERPT_FROM_NEWS_FILE@
+
+Please report bugs to <address@hidden>, along with the output of 'make
+check' and any other information that might be useful in resolving the
+issue.
+
+
+8. Full release note template
+=============================
+
+To: address@hidden
+To: address@hidden, address@hidden, address@hidden
+Subject: GNU M4 @VERSION@ released.
+
+The GNU M4 Team is pleased to announce the release of GNU M4 @address@hidden
+
+GNU `m4' is an implementation of the traditional Unix macro processor.
+It is mostly SVR4 compatible, although it has some extensions (for
+example, handling more than 9 positional parameters to macros). `m4'
+also has built-in functions for including files, running shell commands,
+doing arithmetic, etc. Autoconf needs GNU `m4' for generating
+`configure' scripts, but not for running them.
+
+This release has @address@hidden
+
+New in @VERSION@: @RELEASE_DATE@
+
+ @EXCERPT_FROM_NEWS_FILE@
+
address@hidden@ is available now from ftp.gnu.org, along with diffs and
+xdeltas against address@hidden@ that are also
+available from ftp.gnu.org. Please use a mirror to reduce stress on the
+main gnu machine:
+
+ http://www.gnu.org/order/ftp.html
+
+Here are the compressed sources:
+
+ ftp://ftp.gnu.org/gnu/m4/address@hidden@.tar.gz address@hidden@]
+ ftp://ftp.gnu.org/gnu/m4/address@hidden@.tar.bz2 address@hidden@]
+
+Here are the xdeltas and diffs against address@hidden@:
+
+ ftp://ftp.gnu.org/gnu/m4/address@hidden@address@hidden@.diff.gz
address@hidden@]
+ ftp://ftp.gnu.org/gnu/m4/address@hidden@address@hidden@.xdelta
address@hidden@]
+
+Here are the gpg detached signatures:
+
+ ftp://ftp.gnu.org/gnu/m4/address@hidden@.tar.gz.sig
+ ftp://ftp.gnu.org/gnu/m4/address@hidden@.tar.bz2.sig
+ ftp://ftp.gnu.org/gnu/m4/address@hidden@address@hidden@.diff.gz.sig
+ ftp://ftp.gnu.org/gnu/m4/address@hidden@address@hidden@.xdelta.sig
+
+You should download the signature named after any tarball you download,
+and then verify its integrity with, for example:
+
+ gpg --verify address@hidden
+
+If that command fails because you don't have the required public key,
+then run this command to import it:
+
+ gpg --keyserver wwwkeys.pgp.net --recv-keys @KEY@
+
+Here are the MD5 and SHA1 checksums:
+
+ @MD5SUM@ address@hidden@.tar.gz
+ @MD5SUM@ address@hidden@.tar.bz2
+ @MD5SUM@ address@hidden@address@hidden@.diff.gz
+ @MD5SUM@ address@hidden@address@hidden@.xdelta
+ @SHA1SUM@ address@hidden@.tar.gz
+ @SHA1SUM@ address@hidden@.tar.bz2
+ @SHA1SUM@ address@hidden@address@hidden@.diff.gz
+ @SHA1SUM@ address@hidden@address@hidden@.xdelta
+
+This release was bootstrapped with @address@hidden
+
+Alternatively, you can fetch the unbootstrapped sourcecode from
+anonymous cvs by using the following commands:
+
+ $ export CVS_RSH=ssh
+ $ cvs -z3 -d :pserver:address@hidden:/sources/m4 \
+ co -r @CVS_RELEASE_TAG@ m4
+
+You will then need to have the latest release versions of Automake
+(@AUTOMAKE_VERSION@) and Autoconf (@AUTOCONF_VERSION@) installed to
+bootstrap the checked out sources yourself.
+
+Please report bugs to <address@hidden>, along with the output of 'make
+check' and any other information that might be useful in resolving the
+issue.
+
+
+--
+Copyright (C) 2004, 2005, 2006 Free Software Foundation, Inc.
+
+The canonical source of this file is maintained with the
+GNU M4 package. Report bugs to address@hidden
+
+GNU M4 is free software; you can redistribute it and/or
+modify it under the terms of the GNU General Public License as
+published by the Free Software Foundation; either version 2
+of the License, or (at your option) any later version.
+
+GNU M4 is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with GNU M4; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+02110-1301 USA
+
+
+Local Variables:
+mode: text
+fill-column: 72
+End:
+vim:tw=72
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- Changes to HACKING,
Eric Blake <=