doc: update README-hacking.

[bison.git] / HACKING

diff --git a/HACKING b/HACKING
index 0fffc9c2fa2fac5362d3d85455da966cfbcdd954..10cac90a188b40c8f926adba151353cfb1eeb2e6 100644 (file)
--- a/HACKING
+++ b/HACKING
@@ -1,8 +1,12 @@
 -*- outline -*-
 
 This file attempts to describe the rules to use when hacking Bison.
 -*- outline -*-
 
 This file attempts to describe the rules to use when hacking Bison.

-Don't put this file into the distribution.  Don't mention it in the
-ChangeLog.
+Don't put this file into the distribution.
+
+Everything related to the development of Bison is on Savannah:
+
+       http://savannah.gnu.org/projects/bison/
+

 
 * Administrivia
 
 
 * Administrivia
 


@@ -21,9 +25,27 @@ 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.
 
 which demonstrates the bug.  Then fix the bug, re-run the test suite,
 and check everything in.
 

+** You may find it useful to install the git-merge-changelog merge driver:
+
+  http://git.sv.gnu.org/gitweb/?p=gnulib.git;a=blob;f=lib/git-merge-changelog.c
+
+When following the generic installation instructions there, keep in mind that
+your clone of Bison's git repository already contains appropriate
+.gitattributes files, and running Bison's bootstrap script will make the
+necessary changes to .git/config.
+
+
+* Hacking
+

 ** Visible changes
 Which include serious bug fixes, must be mentioned in NEWS.
 
 ** Visible changes
 Which include serious bug fixes, must be mentioned in NEWS.
 

+** Translations
+Only user visible strings are to be translated: error messages, bits
+of the .output file etc.  This excludes impossible error messages
+(comparable to assert/abort), and all the --trace output which is
+meant for the maintainers only.
+

 
 * Test suite
 
 
 * Test suite
 


@@ -38,35 +60,47 @@ release:
   that 1. Bison compiles cleanly, 2. the parsers it produces compile
   cleanly too.
 
   that 1. Bison compiles cleanly, 2. the parsers it produces compile
   cleanly too.
 

-- Change tests/bison to run `valgrind -q bison' to run Bison under
-  Valgrind.
+- run `make maintainer-check' which:
+  - runs `valgrind -q bison' to run Bison under Valgrind.
+  - runs the parsers under Valgrind.
+  - runs the test suite with G++ as C compiler...

 
 

-- Run the test suite with `./testsuite PREPARSER='valgrind -q' to make
-  sure the parser behave properly.
+- run `make maintainer-push-check', which runs `make maintainer-check'
+  while activating the push implementation and its pull interface wrappers
+  in many test cases that were originally written to exercise only the
+  pull implementation.  This makes certain the push implementation can
+  perform every task the pull implementation can.
+
+- run `make maintainer-xml-check', which runs `make maintainer-check'
+  while checking Bison's XML automaton report for every working grammar
+  passed to Bison in the test suite.  The check just diffs the output of
+  Bison's included XSLT style sheets with the output of --report=all and
+  --graph.

 
 - Change tests/atlocal/CFLAGS to add your preferred options.  For
   instance, `-traditional' to check that the parsers are K&R.  Note
   that it does not make sense for glr.c, which should be ANSI,
 
 - Change tests/atlocal/CFLAGS to add your preferred options.  For
   instance, `-traditional' to check that the parsers are K&R.  Note
   that it does not make sense for glr.c, which should be ANSI,

-  but currently is actually GNU C, nor for lalr1.cc, which anyway is
-  not exercised yet in the test suite.
-
-- Change tests/atlocal/CC to use a C++ compiler.
+  but currently is actually GNU C, nor for lalr1.cc.

 
 
 * Release Procedure
 
 
 
 * Release Procedure
 

+** Try to get the *.pot files to the Translation Project at least one week
+before a stable release, to give them time to translate them.
+

 ** Tests
 See above.
 
 ** Update the foreign files
 ** Tests
 See above.
 
 ** Update the foreign files

-Running `make update' in the top level should make it all for you.
-This covers PO files too.  Beware that it happens that some PO files
-contain serious problems and are rejected by recent Gettext releases:
-fix them all, and complain to the Translation Project!
+Running `./bootstrap' in the top level should update them all for you.
+This covers PO files too.  Sometimes a PO file contains problems that
+causes it to be rejected by recent Gettext releases; please report
+these to the Translation Project.

 
 

-Note that there might be *new* PO files.  Don't forget to update the
-whole machinery, which not only includes LINGUAS, but `cvs add'ing the
-PO files too.
+** Update README
+Make sure the information in this file is current.  Most notably, make sure it
+recommends a version of GNU M4 that is compatible with the latest Bison
+sources.

 
 ** Update NEWS
 The version number, *and* the date of the release (including for
 
 ** Update NEWS
 The version number, *and* the date of the release (including for


@@ -74,9 +108,28 @@ betas).
 
 ** Update ChangeLog
 Should have an entry similar to `Version 1.49b.'.
 
 ** Update ChangeLog
 Should have an entry similar to `Version 1.49b.'.

-Check all this in once `make distcheck' passes.
+
+** Update configure.ac
+Be sure PACKAGE_COPYRIGHT_YEAR is up-to-date.
+
+** Tag the release
+Before Bison will build with the right version number, you must tag the release
+in git.  Do this after all other changes.  The command is similar to:
+
+  git tag -a v2.3b
+
+The log message can be simply:
+
+  Bison 2.3b
+
+** Push
+Once `make distcheck' passes, push your changes and the tag.
+`git push' without arguments will not push the tag.

 
 ** make alpha
 
 ** make alpha

+FIXME: `make alpha' is not maintained and is broken.  These
+instructions need to be replaced or removed.
+

 Running `make alpha' is absolutely perfect for beta releases: it makes
 the tarballs, the xdeltas, and prepares (in /tmp/) a proto
 announcement.  It is so neat, that that's what I use anyway for
 Running `make alpha' is absolutely perfect for beta releases: it makes
 the tarballs, the xdeltas, and prepares (in /tmp/) a proto
 announcement.  It is so neat, that that's what I use anyway for


@@ -88,35 +141,79 @@ If it fails, you're on your own...
 It requires GNU Make.
 
 ** Upload
 It requires GNU Make.
 
 ** Upload

-Put the tarballs/xdeltas where they should be.  Or put it somewhere,
-and send the URL to ftp-upload@gnu.org.
+The generic GNU upload procedure is at:

 
 

-** Bump the version number
-In configure.ac.  Run `make', check this in.
+  http://www.gnu.org/prep/maintain/maintain.html#Automated-FTP-Uploads
+
+Follow the instructions there to register your information so you're permitted
+to upload.  Make sure your public key has been uploaded at least to
+keys.gnupg.net.  You can upload it with:
+
+  gpg --keyserver keys.gnupg.net --send-keys F125BDF3
+
+where F125BDF3 should be replaced with your key ID.
+
+Here's a brief reminder of how to roll the tarballs and upload them:
+
+*** make distcheck
+*** gpg -b bison-2.3b.tar.gz
+*** In a file named `bison-2.3b.tar.gz.directive', type:
+
+      version: 1.1
+      directory: bison
+      filename: bison-2.3b.tar.gz
+
+*** gpg --clearsign bison-2.3b.tar.gz.directive
+*** ftp ftp-upload.gnu.org # Log in as anonymous.
+*** cd /incoming/alpha # cd /incoming/ftp for full release.
+*** put bison-2.3b.tar.gz # This can take a while.
+*** put bison-2.3b.tar.gz.sig
+*** put bison-2.3b.tar.gz.directive.asc
+*** Repeat all these steps for bison-2.3b.tar.bz2.

 
 ** Announce
 
 ** Announce

+To generate a template announcement file:
+
+  make RELEASE_TYPE=alpha gpg_key_ID=F125BDF3 announcement
+
+where alpha can be replaced by beta or major and F125BDF3 should be replaced
+with your key ID.  For an example of how to fill out the template, search the
+mailing list archives for the most recent release announcement.
+

 Complete/fix the announcement file, and send it at least to
 Complete/fix the announcement file, and send it at least to

-info@gnu.org (if a real release, or a ``serious beta''),
-bison@gnu.org, and translation@iro.umontreal.ca.
+info-gnu@gnu.org (if a real release, or a ``serious beta''),
+bug-bison@gnu.org, help-bison@gnu.org, bison-patches@gnu.org,
+and coordinator@translationproject.org.
+
+Send the same announcement on the comp.compilers newsgroup by sending
+email to compilers@iecc.com.  Do not make any Cc as the moderator will
+throw away anything cross-posted or Cc'ed.  It really needs to be a
+separate message.
+
+** Bump the version number
+In configure.ac.  Run `make'.  So that developers don't accidentally add new
+items to the old NEWS entry, create a new empty NEWS entry something like:
+
+  Changes in version ?.? (????-??-??):
+
+Push these changes.

 
 
 -----
 
 
 
 -----
 

-Copyright (C) 2002 Free Software Foundation, Inc.
+Copyright (C) 2002, 2003, 2004, 2005, 2007, 2008 Free Software Foundation, Inc.

 
 This file is part of GNU Bison.
 
 
 This file is part of GNU Bison.
 

-GNU Bison is free software; you can redistribute it and/or modify
+This program is free software: you can redistribute it and/or modify

 it under the terms of the GNU General Public License as published by
 it under the terms of the GNU General Public License as published by

-the Free Software Foundation; either version 2, or (at your option)
-any later version.
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.

 
 

-GNU Bison is distributed in the hope that it will be useful,
+This program 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
 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 Bison; see the file COPYING.  If not, write to the Free
-Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
-02111-1307, USA.
+along with this program.  If not, see <http://www.gnu.org/licenses/>.