HACKING

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:
    https://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):
    https://www.opengroup.org/onlinepubs/009695399/utilities/m4.html


3. Bootstrapping
================

* The master M4 repository is stored in git.

* Before you can build from git, you need to bootstrap.  This requires:
  - A pre-installed version of GNU M4 1.4.6 or later, built from a package
  - Autoconf 2.69 or later
  - Automake 1.14 or later
  - Gettext 0.19.2 or later
  - Help2man 1.29 or later
  - Xz 4.999.8beta or later (from <http://tukaani.org/xz/>)
  - Texinfo 7.0 or later
  - Any prerequisites of the above (such as perl, python3, tex)

  Note that none of these bootstrapping dependencies should be required
  by a distributed release.

* M4 has an optional build dependency.  In order to ensure that the
  dependency remains optional, you can avoid the library by using
  `./configure --without-libsigsegv-prefix'.  In order to ensure that
  the dependency is still viable with the current code base, you should
  install:
  - Libsigsegv 2.6 or later (2.9 or later recommended)

* M4 includes gnulib and bootstrap as git submodules.  By default, the
  bootstrap script will attempt to run
    git submodule update --init
  to grab a gnulib clone from the official location of
    https://git.savannah.gnu.org/git/gnulib.git

  However, this can be network and disk intensive.  If you already have
  another gnulib clone on your disk, using that as a reference can
  speed the process up.  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:
    CONFIG_SHELL=path/to/sh \
      path/to/sh ./bootstrap --gnulib-srcdir=path/to/gnulib

  A read-only copy of gnulib can be obtained by:
      git clone https://git.savannah.gnu.org/git/gnulib.git

  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.https://git.savannah.gnu.org/r/.insteadof \
      git://git.sv.gnu.org/
  to force git to transparently rewrite all savannah git references to
  instead use https.

  Note that none of these bootstrapping dependencies should be required
  by a distributed release.

* 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.

* 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.

* For branch-1.6, the testsuite is generated from the documentation.
  All instances of @example in doc/m4.texi that are not preceded by
  "@comment ignore" are turned into tests in the checks directory.


5. Continuous Integration
=========================

* The package is built automatically, at regular intervals.  You can
  find the latest build results here:
    https://gitlab.com/gnu-m4/ci-distcheck/pipelines
    https://gitlab.com/gnu-m4/ci-distcheck/-/jobs?scope=finished


6. 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:

    https://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.

7. 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.


8. 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 appropriate up-to-date tools installed, including:
  wget
  GNU make
  help2man
  texi2dvi

* 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 'maint: update gnulib submodule to latest' gnulib

* 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.

* Make sure README properly describes the current release type (stable,
  alpha, or current).

* Run `git commit' from the source tree if there are any changes from
  the previous steps.

* Run `make release-commit RELEASE="X.Y $type"' (for the correct X.Y and
  release type), to update the version number in NEWS.  See
  https://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).  This tags the potential release, but 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>; git reset --hard HEAD^' to undo the tag, 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, as well as
  spell out the preferred gnupload commands to use in the next step, and
  create a post-release commit that updates NEWS for subsequent edits.

* Run './build-aux/gnupload --to [dest].gnu.org:m4 --symlink-regex [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 ~/announce-m4-<version>, created during the above
  `make <target>' run, as a starting point.  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 https://www.gnu.org/software/libtool/contribute.html for details of
  the numbering scheme.

* Run `git push origin refs/tags/v<version>' to push the release tag and
  complete the release.

* For non-alpha releases, update the webpages accessible via
    https://www.gnu.org/software/m4/manual/
  by running this:
    build-aux/gnu-web-doc-update --mirror
  You may also need to add a --user=YOUR_SAVANNAH_USERNAME option.

  You may also need to update the main landing page
    https://www.gnu.org/software/m4/
  by running this:
    cvs -d $YOUR_SAVANNAH_USERNAME@cvs.sv.gnu.org:/webcvs/m4 co m4
    # edit m4/m4.html
    cvs -d $YOUR_SAVANNAH_USERNAME@cvs.sv.gnu.org:/webcvs/m4 ci

* Post a news blurb on https://savannah.gnu.org/projects/m4.

* Inform the translation project of the release.  Send mail to:
  coordinator@translationproject.org with the subject "m4-VERSION.pot"
  and a link to the tarball download URL in the body.

* 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-2014, 2016-2017, 2020-2025 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 <https://www.gnu.org/licenses/>.

Local Variables:
mode: text
fill-column: 72
End:
vim:tw=72