HACKING

================================================================
= This file

* This file attempts to describe the rules to use when hacking
  automake.

* Don't put this file into the distribution.  Don't mention it in the
  ChangeLog.


================================================================
= Administrivia

* If you incorporate a change from somebody on the net:
  First, if it is a large change, you must make sure they have signed the
  appropriate paperwork.
  Second, be sure to add their name and email address to THANKS

* If a change fixes a test, mention the test in the ChangeLog entry.

* If somebody reports a new bug, mention his name in the ChangeLog entry
  and in the test case you write.  Put him into THANKS.

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

* Some files in the automake package are not owned by automake.  These
  files should never be edited here.  These files are COPYING, INSTALL,
  ansi2knr.1, ansi2knr.c, config.guess config.sub, install-sh, mdate-sh,
  missing, mkinstalldirs, texinfo.tex

* Changes other than bug fixes must be mentioned in NEWS


================================================================
= Naming

* We've adopted the convention that internal AC_SUBSTs should be
  named with a leading `am__', and internally generated targets should
  be named with a leading `am--'.  This convention is very new
  (as of Feb 7 2001) and so it isn't yet universally used.  But all
  new code should use it.

  We used to use `_am_' as the prefix for an internal AC_SUBST.
  However, it turns out that NEWS-OS 4.2R complains if a Makefile
  variable begins with `_'.  Yay for them.  I changed the target
  naming convention just to be safe.

================================================================
= Editing `.am' files

* Always use $(...) and not ${...}

* Use `:', not `true'.  Use `exit 1', not `false'.

* Use `##' comments liberally.  Comment anything even remotely
  unusual.

* Never use basename or dirname.  Instead use sed

* If you run `cd' within back-quotes, make sure you set `CDPATH=:',
  otherwise the directory name may be printed, depending on CDPATH.

* For install and uninstall rules, if a loop is required, it should be
  silent.  Then the body of the loop itself should print each
  "important" command it runs.  The printed commands should be preceded
  by a single space.


================================================================
= Editing automake.in and aclocal.in

* Follow existing indentation style.

* Perl 5 is now OK.


================================================================
= Test suite

* Use "make check" and "make maintainer-check" liberally

* Make sure each test file is executable


================================================================
= Release procedure

* Fetch new versions of the files that are maintained by the FSF.
  Commit.  Unfortunately you need an FSF account to do this.
  (You can also use `make fetch', but that is still woefully incomplete.)

* Update NEWS.  For an alpha release, update README-alpha.

* Update the version number in configure.in.
  (The idea is that every other alpha number will be a net release.
  The repository will always have its own "odd" number so we can easily
  distinguish net and repo versions.)

* Configure, build, and install.

* Run aclocal, automake, and autoconf.

* Commit

* Run `make cvs-dist'

* Put new release on ftp site and send announcement.
  (If not an alpha, announcement must also go to FSF.)

* Update version number in configure.in to next alpha number.
  Re-run autoconf and commit.