maint: update release procedure
[bison.git] / README-hacking
0 / 408 (  0%)
CommitLineData
1-*- outline -*-
2
3This file attempts to describe the rules to use when hacking Bison.
4Don't put this file into the distribution.
5
6Everything 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:
14First, if it is a large change, you must make sure they have signed
15the appropriate paperwork. Second, be sure to add their name and
16email address to THANKS.
17
18** If a change fixes a test, mention the test in the commit message.
19
20** Bug reports
21If somebody reports a new bug, mention his name in the commit message
22and in the test case you write. Put him into THANKS.
23
24The correct response to most actual bugs is to write a new test case
25which demonstrates the bug. Then fix the bug, re-run the test suite,
26and check everything in.
27
28
29* Hacking
30
31** Visible changes
32Which include serious bug fixes, must be mentioned in NEWS.
33
34** Translations
35Only user visible strings are to be translated: error messages, bits
36of the .output file etc. This excludes impossible error messages
37(comparable to assert/abort), and all the --trace output which is
38meant for the maintainers only.
39
40
41* Working from the repository
42
43These notes intend to help people working on the checked-out sources.
44These requirements do not apply when building from a distribution tarball.
45
46** Requirements
47
48We've opted to keep only the highest-level sources in the repository.
49This eases our maintenance burden, (fewer merges etc.), but imposes more
50requirements on anyone wishing to build from the just-checked-out sources.
51For example, you have to use the latest stable versions of the maintainer
52tools we depend upon, including:
53
54- Automake <http://www.gnu.org/software/automake/>
55- Autoconf <http://www.gnu.org/software/autoconf/>
56- Flex <http://www.gnu.org/software/flex/>
57- Gettext <http://www.gnu.org/software/gettext/>
58- Gzip <http://www.gnu.org/software/gzip/>
59- Perl <http://www.cpan.org/>
60- Rsync <http://samba.anu.edu.au/rsync/>
61- Tar <http://www.gnu.org/software/tar/>
62
63Valgrind <http://valgrind.org/> is also highly recommended, if
64Valgrind supports your architecture.
65
66Bison is written using Bison grammars, so there are bootstrapping
67issues. The bootstrap script attempts to discover when the C code
68generated from the grammars is out of date, and to bootstrap with an
69out-of-date version of the C code, but the process is not foolproof.
70Also, you may run into similar problems yourself if you modify Bison.
71
72Only building the initial full source tree will be a bit painful.
73Later, after synchronizing from the repository a plain 'make' should
74be sufficient. Note, however, that when gnulib is updated, running
75'./bootstrap' again might be needed.
76
77** First checkout
78
79Obviously, if you are reading these notes, you did manage to check out
80this package from the repository. For the record, you will find all the
81relevant information on:
82
83 http://savannah.gnu.org/git/?group=bison
84
85Bison uses Git submodules: subscriptions to other Git repositories.
86In particular it uses gnulib, the GNU portability library. To ask Git
87to perform the first checkout of the submodules, run
88
89 $ git submodule update --init
90
91Git submodule support is weak before versions 1.6 and later, you
92should probably upgrade Git if your version is older.
93
94The next step is to get other files needed to build, which are
95extracted from other source packages:
96
97 $ ./bootstrap
98
99And there you are! Just
100
101 $ ./configure
102 $ make
103 $ make check
104
105At this point, there should be no difference between your local copy,
106and the master copy:
107
108 $ git diff
109
110should output no difference.
111
112Enjoy!
113
114** Updating
115
116The use of submodules make things somewhat different because git does
117not support recursive operations: submodules must be taken care of
118explicitly by the user.
119
120*** Updating Bison
121
122If you pull a newer version of a branch, say via "git pull", you might
123import requests for updated submodules. A simple "git diff" will
124reveal if the current version of the submodule (i.e., the actual
125contents of the gnulib directory) and the current request from the
126subscriber (i.e., the reference of the version of gnulib that the
127Bison reporitory requests) differ. To upgrade the submodules (i.e.,
128to check out the version that is actually requested by the subscriber,
129run "git submodule update".
130
131 $ git pull
132 $ git submodule update
133
134*** Updating a submodule
135To update a submodule, say gnulib, do as follows:
136
137Get the most recent version of the master branch from git.
138
139 $ cd gnulib
140 $ git fetch
141 $ git checkout -b master --track origin/master
142
143Make sure Bison can live with that version of gnulib.
144
145 $ cd ..
146 $ ./bootstrap
147 $ make distcheck
148
149Register your changes.
150
151 $ git checkin ...
152
153For a suggestion of what gnulib commit might be stable enough for a
154formal release, see the ChangeLog in the latest gnulib snapshot at:
155
156 http://erislabs.net/ianb/projects/gnulib/
157
158The autoconf files we use are currently:
159
160 m4/m4.m4
161 lib/m4sugar/m4sugar.m4
162 lib/m4sugar/foreach.m4
163
164These files don't change very often in Autoconf, so it should be
165relatively straight-forward to examine the differences in order to
166decide whether to update.
167
168* Test suite
169
170** make check
171Use liberally.
172
173** Release checks
174Try to run the test suite with more severe conditions before a
175release:
176
177- Configure the package with --enable-gcc-warnings, so that one checks
178 that 1. Bison compiles cleanly, 2. the parsers it produces compile
179 cleanly too.
180
181- Maybe build with -DGNULIB_POSIXCHECK, which suggests gnulib modules
182 that can fix portability issues. See if you really want to pay
183 attention to its warnings; there's no need to obey blindly to it
184 (<http://lists.gnu.org/archive/html/bison-patches/2012-05/msg00057.html>).
185
186- Check with "make syntax-check" if there are issues diagnosed by
187 gnulib.
188
189- run "make maintainer-check" which:
190 - runs "valgrind -q bison" to run Bison under Valgrind.
191 - runs the parsers under Valgrind.
192 - runs the test suite with G++ as C compiler...
193
194- run "make maintainer-push-check", which runs "make maintainer-check"
195 while activating the push implementation and its pull interface wrappers
196 in many test cases that were originally written to exercise only the
197 pull implementation. This makes certain the push implementation can
198 perform every task the pull implementation can.
199
200- run "make maintainer-xml-check", which runs "make maintainer-check"
201 while checking Bison's XML automaton report for every working grammar
202 passed to Bison in the test suite. The check just diffs the output of
203 Bison's included XSLT style sheets with the output of --report=all and
204 --graph.
205
206- running "make maintainer-release-check" takes care of running
207 maintainer-check, maintainer-push-check and maintainer-xml-check.
208
209- Change tests/atlocal/CFLAGS to add your preferred options. For
210 instance, "-traditional" to check that the parsers are K&R. Note
211 that it does not make sense for glr.c, which should be ANSI, but
212 currently is actually GNU C, nor for lalr1.cc.
213
214
215* Release Procedure
216This section needs to be updated to take into account features from
217gnulib. In particular, be sure to read README-release.
218
219** Update the submodules. See above.
220
221** Update maintainer tools, such as Autoconf. See above.
222
223** Try to get the *.pot files to the Translation Project at least one
224week before a stable release, to give them time to translate them.
225Before generating the *.pot files, make sure that po/POTFILES.in and
226runtime-po/POTFILES.in list all files with translatable strings.
227This helps: grep -l '\<_(' *
228
229** Tests
230See above.
231
232** Update the foreign files
233Running "./bootstrap" in the top level should update them all for you.
234This covers PO files too. Sometimes a PO file contains problems that
235causes it to be rejected by recent Gettext releases; please report
236these to the Translation Project.
237
238** Update README
239Make sure the information in README is current. Most notably, make sure
240it recommends a version of GNU M4 that is compatible with the latest
241Bison sources.
242
243** Check copyright years.
244We update years in copyright statements throughout Bison once at the
245start of every year by running "make update-copyright". However, before
246a release, it's good to verify that it's actually been run. Besides the
247copyright statement for each Bison file, check the copyright statements
248that the skeletons insert into generated parsers, and check all
249occurrences of PACKAGE_COPYRIGHT_YEAR in configure.ac.
250
251** Update NEWS
252The version number, *and* the date of the release (including for
253betas).
254
255** Mention the release name in a commit message
256Should have an entry similar to "Version 2.3b.".
257
258** Tag the release
259Before Bison will build with the right version number, you must tag
260the release in git. Do this after all other changes. The command is
261similar to:
262
263 git tag -a v2.3b -m "Bison 2.3b."
264
265** Push
266Once "make distcheck" passes, push your changes and the tag.
267"git push" without arguments will not push the tag.
268
269** make alpha, beta, or release
270See README-release.
271
272** Upload
273There are two ways to upload the tarballs to the GNU servers: using
274gnupload (from gnulib), or by hand. Obviously prefer the former. But
275in either case, be sure to read the following paragraph.
276
277*** Setup
278You need "gnupg".
279
280Make sure your public key has been uploaded at least to
281keys.gnupg.net. You can upload it with:
282
283 gpg --keyserver keys.gnupg.net --send-keys F125BDF3
284
285where F125BDF3 should be replaced with your key ID.
286
287*** Using gnupload
288You need "ncftp".
289
290At the end "make release" (or alpha/beta) will display the prodecure
291to run. Just copy and paste it in your shell.
292
293*** By hand
294
295The generic GNU upload procedure is at:
296
297 http://www.gnu.org/prep/maintain/maintain.html#Automated-FTP-Uploads
298
299Follow the instructions there to register your information so you're permitted
300to upload.
301
302Here's a brief reminder of how to roll the tarballs and upload them:
303
304*** make distcheck
305*** gpg -b bison-2.3b.tar.gz
306*** In a file named "bison-2.3b.tar.gz.directive", type:
307
308 version: 1.1
309 directory: bison
310 filename: bison-2.3b.tar.gz
311
312*** gpg --clearsign bison-2.3b.tar.gz.directive
313*** ftp ftp-upload.gnu.org # Log in as anonymous.
314*** cd /incoming/alpha # cd /incoming/ftp for full release.
315*** put bison-2.3b.tar.gz # This can take a while.
316*** put bison-2.3b.tar.gz.sig
317*** put bison-2.3b.tar.gz.directive.asc
318*** Repeat all these steps for bison-2.3b.tar.xz.
319
320** Update Bison manual on www.gnu.org.
321
322*** You need a non-anonymous checkout of the web pages directory.
323
324 $ cvs -d YOUR_USERID@cvs.savannah.gnu.org:/web/bison checkout bison
325
326*** Get familiar with the instructions for web page maintainers.
327http://www.gnu.org/server/standards/readme_index.html
328http://www.gnu.org/server/standards/README.software.html
329especially the note about symlinks.
330
331*** Build the web pages.
332Assuming BISON_CHECKOUT refers to a checkout of the Bison dir, and
333BISON_WWW_CHECKOUT refers to the web directory created above, do:
334
335 $ cd $BISON_CHECKOUT/doc
336 $ make stamp-vti
337 $ ../build-aux/gendocs.sh -o "$BISON_WWW_CHECKOUT/manual" \
338 bison "Bison - GNU parser generator"
339 $ cd $BISON_WWW_CHECKOUT
340
341Verify that the result looks sane.
342
343*** Commit the modified and the new files.
344
345*** Remove old files.
346Find the files which have not been overwritten (because they belonged to
347sections that have been removed or renamed):
348
349 $ cd manual/html_node
350 $ ls -lt
351
352Remove these files and commit their removal to CVS. For each of these
353files, add a line to the file .symlinks. This will ensure that
354hyperlinks to the removed files will redirect to the entire manual; this
355is better than a 404 error.
356
357There is a problem with 'index.html' being written twice (once for POSIX
358function 'index', once for the table of contents); you can ignore this
359issue.
360
361** Announce
362To generate a template announcement file:
363
364 make RELEASE_TYPE=alpha gpg_key_ID=F125BDF3 announcement
365
366where alpha can be replaced by beta or stable and F125BDF3 should be
367replaced with your key ID.
368
369Complete/fix the announcement file. The generated list of recipients
370(info-gnu@gnu.org, bug-bison@gnu.org, help-bison@gnu.org,
371bison-patches@gnu.org, and coordinator@translationproject.org) is
372appropriate for a stable release or a "serious beta". For any other
373release, drop at least info-gnu@gnu.org. For an example of how to
374fill out the rest of the template, search the mailing list archives
375for the most recent release announcement.
376
377For a stable release, send the same announcement on the comp.compilers
378newsgroup by sending email to compilers@iecc.com. Do not make any Cc as
379the moderator will throw away anything cross-posted or Cc'ed. It really
380needs to be a separate message.
381
382** Bump the version number
383In configure.ac. Run "make". So that developers don't accidentally add new
384items to the old NEWS entry, create a new empty NEWS entry something like:
385
386 Changes in version ?.? (????-??-??):
387
388Push these changes.
389
390
391-----
392
393Copyright (C) 2002-2005, 2007-2012 Free Software Foundation, Inc.
394
395This file is part of GNU Bison.
396
397This program is free software: you can redistribute it and/or modify
398it under the terms of the GNU General Public License as published by
399the Free Software Foundation, either version 3 of the License, or
400(at your option) any later version.
401
402This program is distributed in the hope that it will be useful,
403but WITHOUT ANY WARRANTY; without even the implied warranty of
404MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
405GNU General Public License for more details.
406
407You should have received a copy of the GNU General Public License
408along with this program. If not, see <http://www.gnu.org/licenses/>.