1 @c -*- coding: utf-8; mode: texinfo; -*-
7 * Minor release checklist::
8 * Major release checklist::
9 * Release extra notes::
10 * Notes on builds with GUB::
14 @node Development phases
15 @section Development phases
17 There are 2 states of development on @code{master}:
21 @item @strong{Normal development}:
24 @item @strong{Build-frozen}:
25 Do not require any additional or updated libraries or make
26 non-trivial changes to the build process. Any such patch (or
27 branch) may not be merged with master during this period.
29 This should occur approximately 1 month before any alpha version
30 of the next stable release, and ends when the next unstable branch
36 After announcing a beta release, branch @code{stable/2.x}. There
37 are 2 states of development for this branch:
40 @item @strong{Normal maintenance}:
41 The following patches @strong{MAY NOT} be merged with this branch:
44 @item Any change to the input syntax. If a file compiled with a
45 previous @code{2.x} (beta) version, then it must compile in the
48 Exception: any bugfix to a Critical issue.
50 @item New features with new syntax @emph{may be committed},
51 although once committed that syntax cannot change during the
52 remainder of the stable phase.
54 @item Any change to the build dependencies (including programming
55 libraries, documentation process programs, or python modules used
56 in the buildscripts). If a contributor could compile a previous
57 lilypond @code{2.x}, then he must be able to compile the new
62 @item @strong{Release prep}:
63 Only translation updates and important bugfixes are allowed.
68 @node Minor release checklist
69 @section Minor release checklist
71 A @qq{minor release} means an update of @code{y} in @code{2.x.y}.
73 @subheading Pre-release
78 Using any system with git pull access (not necessarily the GUB
79 build machine), use the commands below to switch to the release
80 branch, get changes and prepare the release
81 announcement. This requires a system which has the release/unstable
82 branch. If you get a warning saying you are in @code{detached HEAD}
83 state, then you should create a release/unstable branch with
84 @code{git checkout release/unstable}.
86 Check the environment variables are set as in
87 @ref{Environment variables}.
89 You need to ensure you have a clean index and work tree. If the
90 checkout displays modified files, you might want to run
91 @code{git reset --hard} before continuing.
95 git checkout release/unstable
96 git merge origin/master
97 make -C $LILYPOND_BUILD_DIR po-replace
98 mv $LILYPOND_BUILD_DIR/po/lilypond.pot po/
99 gedit Documentation/web/news-front.itexi Documentation/web/news.itexi
105 VERSION_DEVEL = the current development version (previous VERSION_DEVEL + 0.01)
108 VERSION_STABLE = the current stable version (probably no change here)
113 Commit, push, switch back to master (or wherever else):
116 git commit -m "Release: bump VERSION_DEVEL." VERSION
117 git commit -m "PO: update template." po/lilypond.pot
118 git commit -m "Release: update news." Documentation/web/
119 git push origin HEAD:release/unstable
124 If you do not have the previous release test-output tarball, download
125 it and put it in @code{regtests/}
127 @item Prepare GUB environment by running:
131 # special terminal, and default PATH environment.
132 # import these special environment vars:
133 # HOME, HTTP_PROXY, TERM
136 HTTP_PROXY=$HTTP_PROXY \
137 bash --rcfile my-bashrc
142 export PS1="\[\e[1;33mGUB-ENV \w\]$ \[\e[0m\]"
148 @item Build release on GUB by running:
151 make LILYPOND_BRANCH=release/unstable lilypond
158 make LILYPOND_BRANCH=stable/2.16 lilypond
162 Check the regtest comparison in @file{uploads/webtest/} for
163 any unintentional breakage. More info in
164 @ref{Precompiled regression tests}.
167 If any work was done on GUB since the last release, upload
168 binaries to a temporary location, ask for feedback, and wait a day
169 or two in case there's any major problems.
171 @warning{Always do this for a stable release.}
176 @subheading Actual release
180 @item If you're not the right user on the webserver, remove the
181 @code{t} from the rsync command in:
184 test-lily/rsync-lily-doc.py
185 test-lily/rsync-test.py
188 @item Upload GUB by running:
191 make lilypond-upload \
192 LILYPOND_REPO_URL=git://git.sv.gnu.org/lilypond.git \
193 LILYPOND_BRANCH=release/unstable
200 make lilypond-upload \
201 LILYPOND_REPO_URL=git://git.sv.gnu.org/lilypond.git \
202 LILYPOND_BRANCH=stable/2.12
208 @subheading Post release
213 Update the current staging branch with the current news:
217 git checkout origin/staging
218 git merge origin/release/unstable
222 Update @file{VERSION} in lilypond git and upload changes:
230 VERSION = what you just did +0.0.1
234 git commit -m "Release: bump VERSION." VERSION
235 git push origin HEAD:staging
238 If the push fails with a message like
241 ! [rejected] HEAD -> staging (non-fast-forward)
245 it means that somebody else updated the staging branch while you were
246 preparing your change. In that case, you need to restart the Post
247 Release process. Otherwise, proceed:
249 @item Wait a few hours for the website to update.
251 @item Email release notice to @code{info-lilypond}
257 @node Major release checklist
258 @section Major release checklist
260 A @qq{major release} means an update of @code{x} in @code{2.x.0}.
262 @subheading Main requirements
264 This is the current official guidelines.
268 0 Critical issues for two weeks (14 days) after the latest release
274 @subheading Potential requirements
276 These might become official guidelines in the future.
283 Check all 2ly scripts
286 Check for emergencies the docs:
289 grep FIXME --exclude "misc/*" --exclude "*GNUmakefile" \
290 --exclude "snippets/*" ????*/*
294 Check for altered regtests, and document as necessary. (update
295 numbers in the following command as appropriate)
298 git diff -u -r release/2.12.0-1 -r release/2.13.13-1 input/regression/
304 @subheading Housekeeping requirements
310 write release notes. note: stringent size requirements for
311 various websites, so be brief.
314 Run convert-ly on all files, bump parser minimum version.
320 make -C $LILYPOND_BUILD_DIR po-replace
321 mv $LILYPOND_BUILD_DIR/po/lilypond.pot po/
325 Make directories on lilypond.org:
328 ~/web/download/sources/v2.14
329 ~/web/download/sources/v2.15
333 Shortly after the release, move all current contributors to
334 previous contributors in:
337 Documentation/included/authors.itexi
340 Also, delete old material in:
343 Documentation/changes.tely
346 but don't forget to check it still compiles! also update the
354 make a link from the old unstable to the next stable in
355 lilypond.org's /doc/ dir. Keep all previous unstable->stable doc
358 Also, make the old docs self-contained -- if there's a redirect in
359 /doc/v2.12/Documentation/index.html , replace it with the
360 index.html.old-2.12 files.
362 The post-2.13 docs will need another way of handling the
363 self-containment. It won't be hard to whip up a python script
364 that changes the link to ../../../../manuals.html to
365 ../website/manuals.html , but it's still a 30-minute task that
366 needs to be done before 2.16.
369 doc auto redirects to v2.LATEST-STABLE
372 add these two lines to http://www.lilypond.org/robots.txt:
375 Disallow: /doc/v2.PREVIOUS-STABLE/
376 Disallow: /doc/v2.CURRENT-DEVELOPMENT/
387 submit po template for translation: send url of tarball to
388 coordinator@@translationproject.org, mentioning lilypond-VERSION.pot
391 update links to distros providing lilypond packages? link in:
392 @file{Documentation/web/download.itexi}
394 This has nothing to do with the release, but it's a "periodic
395 maintenance" task that might make sense to include with releases.
398 Send announcements to...
404 comp.os.linux.announce
413 info-lilypond@@gnu.org
415 linux-audio-announce@@lists.linuxaudio.org
416 linux-audio-user@@lists.linuxaudio.org
417 linux-audio-dev@@lists.linuxaudio.org
419 tex-music@@icking-music-archive.org
422 abcusers@@blackmill.net
424 rosegarden-user@@lists.sourceforge.net
426 noteedit-user@@berlios.de
428 gmane.comp.audio.fomus.devel
429 gmane.linux.audio.users
430 gmane.linux.audio.announce
431 gmane.comp.audio.rosegarden.devel
440 http://www.apple.com/downloads
441 harmony-central.com (news@@harmony-central.com)
442 versiontracker.com [auto]
445 https://savannah.gnu.org/news/submit.php?group_id=1673 @c => planet.gnu.org
451 @node Release extra notes
452 @section Release extra notes
454 @subsubheading Regenerating regression tests
456 Regenerating regtests (if the lilypond-book naming has changed):
461 git checkout release/lilypond-X.Y.Z-A
464 take lilypond-book and any related makefile updates from the
468 configure; make; make test
471 tar -cjf lilypond-X.Y.Z-A.test-output.tar.bz2 input/regression/out-test/
474 mv lilypond-X.Y.Z-A.test-output.tar.bz2 ../gub/regtests/
485 @subsubheading stable/2.12
487 If releasing stable/2.12, then:
492 apply doc patch: patches/rsync-lily.patch (or something like
496 change infodir in gub/specs/lilypond-doc.py from "lilypond.info"
497 to "lilypond-web.info"
500 @subsubheading Updating a release (changing a in x.y.z-a)
502 Really tentative instructions, almost certainly can be done
508 change the VERSION back to release you want. push change.
509 (hopefully you'll have forgotten to update it when you made your
513 make sure that there aren't any lilypond files floating around in
514 target/ (like usr/bin/lilypond).
517 build the specific package(s) you want, i.e.
520 bin/gub mingw::lilypond-installer
521 make LILYPOND_BRANCH=stable/2.12 -f lilypond.make doc
522 bin/gub --platform=darwin-x86 \
523 'git://git.sv.gnu.org/lilypond-doc.git?branch=stable/2.12'
528 build everything with the normal "make lilypond", then (maybe)
529 manually delete stuff you don't want to upload.
532 manually upload them. good luck figuring out the rsync
533 command(s). Hints are in test-lily/
537 run the normal lilypond-upload command, and (maybe) manually
538 delete stuff you didn't want to upload from the server.
542 @node Notes on builds with GUB
543 @section Notes on builds with GUB
545 @subsubheading Building GUB
547 GUB - the Grand Unified Builder - is used to build the release
548 versions of LilyPond. For background information, see
549 @ref{Grand Unified Builder (GUB)}. The simplest way to set up a
550 GUB build environment is to use a virtual machine with LilyDev
551 (@ref{LilyDev}). Follow the instructions on that page to set this
552 up. Make sure that your virtual machine has enough disk space -
553 a GUB installation takes over 30 GBytes of disk space, and if you
554 allocate too little, it will fail during the setting up stage and
555 you will have to start again. 64 GBytes should be sufficient.
557 While GUB is being built, any interruptions are likely to make it
558 almost impossible to restart. If at all possible, leave the build
559 to continue uninterrupted.
561 Download GUB and start the set up:
564 git clone git://github.com/gperciva/gub/gub.git
569 This will take a very long time, even on a very fast computer.
570 You will need to be patient. It's also liable to fail - it
571 downloads a number of tools, and some will have moved and others
572 won't respond to the network. For example, the perl archive.
573 If this happens, download it from
574 @uref{http://www.cpan.org/src/5.0/perl-5.10.0.tar.gz}, saving the
575 archive to @file{gub/downloads/perl/}. Continue the set up with:
581 Once this has completed successfully, you can build the LilyPond
582 release package. However, this uses an archived version of the
583 regression tests, so it is better to download this first.
584 Download the test output from lilypond.org (you will need to
585 replace @code{2.15.33-1} with the latest build):
588 @uref{http://lilypond.org/download/binaries/test-output/lilypond-2.15.33-1.test-output.tar.bz2}
591 Copy the tarball into @file{gub/regtests/}, and tell the build
592 system that you have done this:
595 touch regtests/ignore
598 Now start the GUB build:
604 That's it. This will build LilyPond from current master. To build
605 the current unstable release, run:
608 make LILYPOND_BRANCH=release/unstable lilypond
611 The first time you do this, it will take a very long time.
613 Assuming the build has gone well, it can be uploaded using:
617 LILYPOND_BRANCH=release/unstable
618 LILYPOND_REPO_URL=git://git.sv.gnu.org/lilypond.git
621 @subsubheading Output files
623 GUB builds the files it needs into the directory
624 @code{gub/target/}. As a general rule, these don't need to be
625 touched unless there is a problem building GUB (see below).
626 The files to be uploaded are in @code{gub/uploads/}. Once the
627 build has completed successfully, there should be 8
628 installation files and 3 archives, totalling about 600MB.
629 There are also 4 directories:
638 @code{signatures} contains files that are used to track whether
639 some of the archives have already been built. Don't touch
642 @code{localdoc} probably contains local copies of the
645 @code{webdoc} contains the documentation to be uploaded.
647 @code{webtest} contains the regtest comparison, which should
648 be checked before upload, and is also uploaded for subsequent
651 The total upload is about 700 MB in total, and on an ADSL
652 connection will take about 4 hours to upload.
654 @subsubheading Subsequent builds
656 In principle, building the next release of LilyPond requires
657 no action other then following the instructions in
658 @ref{Minor release checklist}. Because much of the
659 infrastructure has already been built, it will take much less
660 time - about an hour on a fast computer.
662 Continuing to build LilyPond without any other
663 archiving/deletion of previous builds is likely to be successful,
664 but will take up a fair amount of disk space (around 2GB per
665 build) which may be a problem with a Virtual Machine. It's
666 therefore recommended to move (not copy) @code{gub/uploads} to
667 another machine/disk after each build, if space is at a premium.
669 However, if a significant change has been made to the LilyPond
670 source (e.g. added source files) the build may fail if tried on
671 top of a previous build. If this happens, be sure to
672 move/delete @code{gub/uploads} and all mentions of LilyPond
673 in @code{gub/target}. The latter can be achieved with this
677 rm -rf target/*/*/*lilypond*
680 Be @emph{very} careful with this command. Typing it wrongly
681 could wipe your disk completely.
683 @subsubheading Updating the web site
685 The @code{make lilypond-upload} command updates the documentation
686 on the LilyPond web site. However, it does @emph{not} update
687 any part of the site that is not part of the documentation - for
688 example, the front page (@code{index.html}). The website is
689 updated by 2 cron jobs running on the web server. One of these
690 pulls git master to the web server, and the other makes the
691 website with the standard @code{make website} command. They run
692 hourly, 30 minutes apart. So - to update the front page of the
693 website, it's necessary to update @code{VERSION} and
694 @code{news-front.itexi} in master and then wait for the cron
695 jobs to run. (N.B. - this is done by pushing the changes to
696 staging and letting patchy do its checks before it pushes to