HACKING

   1 -*- outline -*-
   2
   3 This file attempts to describe the rules to use when hacking Bison.
   4 Don't put this file into the distribution.
   5
   6 Everything related to the development of Bison is on Savannah:
   7
   8         http://savannah.gnu.org/projects/bison/
   9
  10
  11 * Administrivia
  12
  13 ** If you incorporate a change from somebody on the net:
  14 First, if it is a large change, you must make sure they have signed
  15 the appropriate paperwork.  Second, be sure to add their name and
  16 email address to THANKS.
  17
  18 ** If a change fixes a test, mention the test in the ChangeLog entry.
  19
  20 ** Bug reports
  21 If somebody reports a new bug, mention his name in the ChangeLog entry
  22 and in the test case you write.  Put him into THANKS.
  23
  24 The correct response to most actual bugs is to write a new test case
  25 which demonstrates the bug.  Then fix the bug, re-run the test suite,
  26 and check everything in.
  27
  28 ** You may find it useful to install the git-merge-changelog merge driver.
  29 See http://www.mail-archive.com/bug-gnulib@gnu.org/msg09699.html for
  30 information on how to install it.
  31
  32
  33 * Hacking
  34
  35 ** Visible changes
  36 Which include serious bug fixes, must be mentioned in NEWS.
  37
  38 ** Translations
  39 Only user visible strings are to be translated: error messages, bits
  40 of the .output file etc.  This excludes impossible error messages
  41 (comparable to assert/abort), and all the --trace output which is
  42 meant for the maintainers only.
  43
  44
  45 * Test suite
  46
  47 ** make check
  48 Use liberally.
  49
  50 ** Release checks
  51 Try to run the test suite with more severe conditions before a
  52 release:
  53
  54 - Configure the package with --enable-gcc-warnings, so that one checks
  55   that 1. Bison compiles cleanly, 2. the parsers it produces compile
  56   cleanly too.
  57
  58 - run `make maintainer-check' which:
  59   - runs `valgrind -q bison' to run Bison under Valgrind.
  60   - runs the parsers under Valgrind.
  61   - runs the test suite with G++ as C compiler...
  62
  63 - run `make maintainer-push-check', which runs `make maintainer-check'
  64   while activating the push implementation and its pull interface wrappers
  65   in many test cases that were originally written to exercise only the
  66   pull implementation.  This makes certain the push implementation can
  67   perform every task the pull implementation can.
  68
  69 - run `make maintainer-xml-check', which runs `make maintainer-check'
  70   while checking Bison's XML automaton report for every working grammar
  71   passed to Bison in the test suite.  The check just diffs the output of
  72   Bison's included XSLT style sheets with the output of --report=all and
  73   --graph.
  74
  75 - Change tests/atlocal/CFLAGS to add your preferred options.  For
  76   instance, `-traditional' to check that the parsers are K&R.  Note
  77   that it does not make sense for glr.c, which should be ANSI,
  78   but currently is actually GNU C, nor for lalr1.cc, which anyway is
  79   not exercised yet in the test suite.
  80
  81
  82 * Release Procedure
  83
  84 ** Try to get the *.pot files to the Translation Project at least one week
  85 before a stable release, to give them time to translate them.
  86
  87 ** Tests
  88 See above.
  89
  90 ** Update the foreign files
  91 Running `./bootstrap' in the top level should update them all for you.
  92 This covers PO files too.  Sometimes a PO file contains problems that
  93 causes it to be rejected by recent Gettext releases; please report
  94 these to the Translation Project.
  95
  96 ** Update NEWS
  97 The version number, *and* the date of the release (including for
  98 betas).
  99
 100 ** Update ChangeLog
 101 Should have an entry similar to `Version 1.49b.'.
 102 Check all this in once `make distcheck' passes.
 103
 104 ** make alpha
 105 Running `make alpha' is absolutely perfect for beta releases: it makes
 106 the tarballs, the xdeltas, and prepares (in /tmp/) a proto
 107 announcement.  It is so neat, that that's what I use anyway for
 108 genuine releases, but adjusting things by hand (e.g., the urls in the
 109 announcement file, the ChangeLog which is not needed etc.).
 110 FIXME: `make alpha' is not maintained and is broken.  These
 111 instructions need to be replaced or removed.
 112
 113 If it fails, you're on your own...
 114
 115 It requires GNU Make.
 116
 117 ** Upload
 118 Put the tarballs/xdeltas where they should be.  Or put it somewhere,
 119 and send the URL to ftp-upload@gnu.org.
 120
 121 ** Bump the version number
 122 In configure.ac.  Run `make', check this in.
 123
 124 ** Announce
 125 Complete/fix the announcement file, and send it at least to
 126 info-gnu@gnu.org (if a real release, or a ``serious beta''),
 127 bug-bison@gnu.org, help-bison@gnu.org, bison-patches@gnu.org,
 128 and coordinator@translationproject.org.
 129
 130 Send the same announcement on the comp.compilers newsgroup by sending
 131 email to compilers@iecc.com.  Do not make any Cc as the moderator will
 132 throw away anything cross-posted or Cc'ed.  It really needs to be a
 133 separate message.
 134
 135
 136 -----
 137
 138 Copyright (C) 2002, 2003, 2004, 2005, 2007, 2008 Free Software Foundation, Inc.
 139
 140 This file is part of GNU Bison.
 141
 142 This program is free software: you can redistribute it and/or modify
 143 it under the terms of the GNU General Public License as published by
 144 the Free Software Foundation, either version 3 of the License, or
 145 (at your option) any later version.
 146
 147 This program is distributed in the hope that it will be useful,
 148 but WITHOUT ANY WARRANTY; without even the implied warranty of
 149 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 150 GNU General Public License for more details.
 151
 152 You should have received a copy of the GNU General Public License
 153 along with this program.  If not, see <http://www.gnu.org/licenses/>.