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