diff options
Diffstat (limited to 'HACKING')
| -rw-r--r-- | HACKING | 334 |
1 files changed, 0 insertions, 334 deletions
diff --git a/HACKING b/HACKING deleted file mode 100644 index 0e5cd66b..00000000 --- a/HACKING +++ /dev/null @@ -1,334 +0,0 @@ -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. - -* New macros must be blind, or else prefixed with `m4' or `__', in - order to minimize backward compatibility issues with previous - releases of M4 when processing English text. - -* 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 - -* Except for third-party files (libtool, gnulib, ...), all .c files - should #include <config.h> before anything else (since there are some - #defines in config.h that potentially impact system headers, such as - when the user does ./configure --disable-assert). This means that no - .h files need to #include <config.h>. However, users compiling - external modules should be able to compile without <config.h>, since - <config.h> is specific to the M4 build and is not installable. - - -3. Bootstrapping -================ - -* The master M4 repository is stored in git. You can obtain a read-only - copy with: - git clone git://git.sv.gnu.org/m4.git - or - cvs -d:pserver:anonymous@pserver.git.sv.gnu.org:/srv/git/m4.git \ - co -d m4 HEAD - - If you are a member of the savannah group for M4, a read-write - copy can be obtained by: - git clone <savannah-user>@git.sv.gnu.org:/srv/git/m4.git - -* Before you can build from git, you need to bootstrap. This requires: - - A pre-installed version of GNU M4 1.4.5 or later, built from a - package (recommend 1.4.13 or later) - - A git checkout of Autoconf (2.63b-41 or later) - - Automake 1.10b or later - - Libtool 2.2 or later - - Gettext 0.16 or later - - Gperf 3.0 or later - - Help2man 1.29 or later - - Xz 4.999.8beta or later (from <http://tukaani.org/xz/>) - - Texinfo 4.8 or later - - Any prerequisites of the above (such as perl, tex) - - Note that none of these bootstrapping dependencies should be required - by a distributed release. - -* M4 includes gnulib as a git submodule. By default, the bootstrap - script will attempt to run - git submodule update --init - to grab a gnulib clone from the official read-only location of - git://git.sv.gnu.org/gnulib.git - - However, this can be network and disk intensive. If you already have - another gnulib clone on your disk, you can use the environment - variable GNULIB_SRCDIR to point to the previous checkout to speed up - the process. Additionally, both the bootstrap script and gnulib-tool - require a shell that supports functions, so you can set the - environment variable CONFIG_SHELL to choose a better shell on systems - (like Solaris) where /bin/sh is lacking. Thus, you may find it - convenient to run: - GNULIB_SRCDIR=path/to/gnulib CONFIG_SHELL=path/to/sh \ - path/to/sh ./bootstrap - - A read-only copy of gnulib can be obtained by: - git clone git://git.sv.gnu.org/gnulib.git - or - cvs -d:pserver:anonymous@pserver.git.sv.gnu.org:/srv/git/gnulib.git \ - co -d gnulib HEAD - - Using a CVS checkout might work, but it is relatively untested, - particularly now that we use a git submodule for gnulib. - - If you are a member of the savannah group for gnulib, a read-write - copy can be obtained by: - git clone <savannah-user>@git.sv.gnu.org:/srv/git/gnulib.git - - If you are behind a firewall that blocks the git protocol, you may - find it useful to do: - git config --global url.http://git.savannah.gnu.org/r/.insteadof \ - git://git.sv.gnu.org/ - to force git to transparently rewrite all savannah git references to - instead use http. - -* 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 git 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. - -* Normally, after running bootstrap, 'git status' should not show any - differences; if things changed, please provide a patch or at least - report it as a bug. One case where things are changed is if the - gnulib submodule comes from an older date than the current installed - libtool, such that libtoolize will replace the symlinks to an older - version of build-aux files with their newer counterpart; the fix to - this is updating the submodule to a newer gnulib version. - -* If you would like to check that you are not missing out on any useful - gnulib modules, comment out the gl_ASSERT_NO_GNULIB_POSIXCHECK in - configure.ac, then run 'make CFLAGS='-DGNULIB_POSIXCHECK=1' with gcc, - and look at the resulting warnings. - - -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' -====================== - -* The ChangeLog is generated from git commit comments. Each commit log - should start with a one-line summary, a blank line, and then a - ChangeLog-style entry for all affected files. However, it's fine -- - even recommended -- to write a few lines of prose describing the - change, when the summary and ChangeLog entries don't give enough of - the big picture. Omit the leading TABs that you're used to seeing in - a "real" ChangeLog file, but keep the maximum line length at 72 or - smaller, so that the generated ChangeLog lines, each with its leading - TAB, will not exceed 80 columns. As for the ChangeLog-style content, - please follow these guidelines: - - http://www.gnu.org/software/guile/changelogs/guile-changelogs_3.html - -* 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, which you can then paste into your git - commit editing session. - -* See the GNU Coding Standards document for more details on ChangeLog - formatting. - -6. Formatting -============= - -* Use space-only indentation in nearly all files (Makefile inputs being - the exception). - - If you use Emacs and your m4 working directory name matches, - this code in your ~/.emacs enables the right mode: - - ;; In m4, indent with spaces everywhere (not TABs). - ;; Exceptions: Makefile and ChangeLog modes. - (add-hook 'find-file-hook '(lambda () - (if (and buffer-file-name - (string-match "/m4\\>" (buffer-file-name)) - (not (string-equal mode-name "Change Log")) - (not (string-equal mode-name "Makefile"))) - (setq indent-tabs-mode nil)))) - -* Since the source code was massively converted from tabs in December - 2009, you may find it helpful to use 'git diff -w' and 'git blame -w' - helpful for overlooking the whitespace changes. - -* Avoid #ifdefs inside function bodies, whenever possible. If you - encounter a portability issue, it is better to propose a gnulib module - that works around it, and have m4 use that module. - - -7. 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 <ftp-upload@gnu.org> 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, but - helps, since by default, m4-announce rejects all posts, so you have to - get an administrator to allow your announcement through. - -* Make sure you have rsync installed. - -* Make sure you have GNU make installed. - -* Make sure you have an up-to-date version of help2man installed. - -* Make sure your locale is sane, e.g. by exporting LC_ALL=C. - -* Make sure you are happy with the particular gnulib version recorded as - the gnulib submodule. If necessary to update to the latest, run: - git submodule foreach git pull origin master - git commit -m 'Update gnulib submodule to latest.' gnulib - In particular, ensure that the gnulib version is at least as new as - the latest stable libtool release. - -* Update the version number in NEWS, and mention in README whether the - release is stable. See - http://www.gnu.org/software/libtool/contribute.html for details of the - numbering scheme (M4 uses a similar scheme to libtool, although - intra-release versions carry more information thanks to - git-version-gen). - -* Run ./bootstrap, perhaps with environment variables set. - -* Run ./configure (a VPATH build should work, but is less tested). - -* Run `make'. The file doc/m4.1 needs to exist for a distribution, and - be up-to-date with m4 --help output, but `make dist' intentionally - does not depend on running a built binary. - -* Run `git commit' from the source tree if there are any changes from - the previous steps. - -* Run `git tag -s -m <version> -u <gpg_key> v<version>' with the desired - version number. Do not push anything upstream at this point. - -* Run `make distcheck'. If there are any problems, fix them, then run - `git tag -d v<version>' and start again from the `git commit' step. - -* Run `make <target>', with target set to `stable', `alpha', or `beta' - as appropriate. This will run various additional checks. - -* Run './build-aux/gnupload --to [dest].gnu.org:m4 [files]' to create - detached gpg signature and clear signed directive files, and upload - the combination to the correct location. For an alpha release, - gnupload will place files in alpha.gnu.org, in /incoming/alpha; for a - full release, gnupload will place files in ftp.gnu.org, in - /incoming/ftp. Verify that the files uploaded successfully before - sending an announcement. - -* Send announcement to m4-discuss@gnu.org, m4-announce@gnu.org, and - autotools-announce@gnu.org. If not an alpha send to info-gnu@gnu.org - as well. Use gnulib/build-aux/announce-gen to form an initial - template for the announcement (you may also need to install the perl - module Digest::SHA1). Contact a list administrator for m4-announce in - advance to ensure your post will make it through (the list is normally - set to silently discard all posts, even from subscribers). - -* 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 and README to start the intra-release changes, and run - `git commit'. Then run `git push origin refs/tags/v<version>' to push - the release tag and complete the release. - -* For stable releases, update the webpages. - Run `build-aux/gnu-web-doc-update', which runs `make web-manual' on a - temporary git branch corresponding to the release, then copies the - contents of doc/manual into a CVS checkout of the M4 manual - repository. Follow up with any needed edits to m4.html, using: - export CVS_RSH=ssh - cvs -z3 -d:ext:<user>@cvs.savannah.gnu.org:/web/m4 co m4 - -* Update the Free Software Directory. Browse to: - http://directory.fsf.org/project/m4/ - and send an email to <bug-directory@gnu.org> mentioning any content - that needs to be updated. - ------------ -Copyright (C) 2004-2010, 2013-2014, 2017 Free Software Foundation, Inc. - -The canonical source of this file is maintained with the -GNU M4 package. Report bugs to bug-m4@gnu.org. - -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 3 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 this program. If not, see <http://www.gnu.org/licenses/>. - -Local Variables: -mode: text -fill-column: 72 -End: -vim:tw=72 |