X-Git-Url: https://git.saurik.com/bison.git/blobdiff_plain/2ed0e35f8662e46abf2d4b591453c82a66581d99..81535bfa352e0a289a6b5448b37b53afb8542d79:/HACKING diff --git a/HACKING b/HACKING index 0fffc9c2..10cac90a 100644 --- a/HACKING +++ b/HACKING @@ -1,8 +1,12 @@ -*- 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 @@ -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. +** 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. +** 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 @@ -38,35 +60,47 @@ release: 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, - 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 +** 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 -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 @@ -74,9 +108,28 @@ betas). ** 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 +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 @@ -88,35 +141,79 @@ If it fails, you're on your own... 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 +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 -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. -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 -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 -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 .