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 do the following:
83 switch to the release branch
86 update the release branch from origin/master
89 update the translation files
92 create the release announcement
95 update the build versions.
99 VERSION_DEVEL = the current development version (previous VERSION_DEVEL + 0.01)
102 VERSION_STABLE = the current stable version (probably no change here)
107 update the @qq{Welcome to Lilypond} version numbers to the version about to be
112 This requires a system which has the release/unstable
113 branch. If you get a warning saying you are in @code{detached HEAD}
114 state, then you should create a release/unstable branch with
115 @code{git checkout release/unstable}.
117 Check the environment variables are set as in
118 @ref{Environment variables}.
120 You need to ensure you have a clean index and work tree. If the
121 checkout displays modified files, you might want to run
122 @code{git reset --hard} before continuing.
126 git checkout release/unstable
127 git merge origin/master
128 make -C $LILYPOND_BUILD_DIR po-replace
129 mv $LILYPOND_BUILD_DIR/po/lilypond.pot po/
130 gedit Documentation/web/news-front.itexi Documentation/web/news.itexi
136 Commit, push, switch back to master (or wherever else):
139 git commit -m "Release: bump VERSION_DEVEL." VERSION
140 git commit -m "Release: bump VERSION_DEVEL." ly/Welcome_to_LilyPond.ly
141 git commit -m "Release: bump VERSION_DEVEL." ly/Welcome-to-LilyPond-MacOS.ly
142 git commit -m "PO: update template." po/lilypond.pot
143 git commit -m "Release: update news." Documentation/web/
144 git commit -m "Release: bump Welcome versions." ly/Wel*.ly
145 git push origin HEAD:release/unstable
150 If you do not have the previous release test-output tarball, download
151 it and put it in @code{regtests/}
153 @item Prepare GUB environment by running:
157 # special terminal, and default PATH environment.
158 # import these special environment vars:
159 # HOME, HTTP_PROXY, TERM
162 HTTP_PROXY=$HTTP_PROXY \
163 bash --rcfile my-bashrc
168 export PS1="\[\e[1;33mGUB-ENV \w\]$ \[\e[0m\]"
174 @item Build release on GUB by running:
177 make LILYPOND_BRANCH=release/unstable lilypond
184 make LILYPOND_BRANCH=stable/2.16 lilypond
188 Check the regtest comparison in @file{uploads/webtest/} for
189 any unintentional breakage. More info in
190 @ref{Precompiled regression tests}.
193 If any work was done on GUB since the last release, upload
194 binaries to a temporary location, ask for feedback, and wait a day
195 or two in case there's any major problems.
197 @warning{Always do this for a stable release.}
202 @subheading Actual release
206 @item If you're not the right user on the webserver, remove the
207 @code{t} from the rsync command in:
210 test-lily/rsync-lily-doc.py
211 test-lily/rsync-test.py
214 @item Upload GUB by running:
217 make lilypond-upload \
218 LILYPOND_REPO_URL=git://git.sv.gnu.org/lilypond.git \
219 LILYPOND_BRANCH=release/unstable
226 make lilypond-upload \
227 LILYPOND_REPO_URL=git://git.sv.gnu.org/lilypond.git \
228 LILYPOND_BRANCH=stable/2.12
234 @subheading Post release
239 Update the current staging branch with the current news:
243 git checkout origin/staging
244 git merge origin/release/unstable
248 Update @file{VERSION} in lilypond git and upload changes:
256 VERSION = what you just did +0.0.1
260 git commit -m "Release: bump VERSION." VERSION
261 git push origin HEAD:staging
264 If the push fails with a message like
267 ! [rejected] HEAD -> staging (non-fast-forward)
271 it means that somebody else updated the staging branch while you were
272 preparing your change. In that case, you need to restart the Post
273 Release process. Otherwise, proceed:
275 @item Wait a few hours for the website to update.
277 @item Email release notice to @code{info-lilypond}
283 @node Major release checklist
284 @section Major release checklist
286 A @qq{major release} means an update of @code{x} in @code{2.x.0}.
288 @subheading Main requirements
290 These are the current official guidelines.
294 0 Critical issues for two weeks (14 days) after the latest release
300 @subheading Potential requirements
302 These might become official guidelines in the future.
309 Check all 2ly scripts
312 Check for emergencies the docs:
315 grep FIXME --exclude "misc/*" --exclude "*GNUmakefile" \
316 --exclude "snippets/*" ????*/*
320 Check for altered regtests, and document as necessary:
323 git diff -u -r release/2.@var{FIRST-CURRENT-STABLE} \
324 -r release/2.@var{LAST-CURRENT-DEVELOPMENT} input/regression/
330 @subheading Housekeeping requirements
336 write release notes. note: stringent size requirements for
337 various websites, so be brief.
340 Run convert-ly on all files, bump parser minimum version.
346 make -C $LILYPOND_BUILD_DIR po-replace
347 mv $LILYPOND_BUILD_DIR/po/lilypond.pot po/
351 Make directories on lilypond.org:
354 ~/download/sources/v2.@var{NEW-STABLE}
355 ~/download/sources/v2.@var{NEW-DEVELOPMENT}
359 Shortly after the release, move all current contributors to
360 previous contributors in
361 @file{Documentation/included/authors.itexi}.
364 Delete old material in @file{Documentation/changes.tely}, but
365 don't forget to check it still compiles! Also update the version
370 @@top New features in 2.@var{NEW-STABLE} since 2.@var{OLD-STABLE}
378 make a link from the old unstable to the next stable in
379 lilypond.org's @file{/doc/} dir. Keep all previous unstable->stable
382 Also, make the old docs self-contained -- if there's a redirect in
383 @file{/doc/v2.@var{OLD-STABLE}/Documentation/index.html} , replace it with the
384 @file{index.html.old-2.@var{OLD-STABLE}} files.
386 The post-2.13 docs will need another way of handling the
387 self-containment. It won't be hard to whip up a python script
388 that changes the link to @file{../../../../manuals.html} to
389 @file{../website/manuals.html}, but it's still a 30-minute task that
390 needs to be done before 2.16.
393 doc auto redirects to @code{v2.@var{NEW-STABLE}}
396 add these two lines to @file{Documentation/web/server/robots.txt}:
399 Disallow: /doc/v2.@var{OLD-STABLE}/
400 Disallow: /doc/v2.@var{NEW-DEVELOPMENT}/
411 submit po template for translation: send url of tarball to
412 @email{coordinator@@translationproject.org}, mentioning
416 update links to distros providing lilypond packages? link in:
417 @file{Documentation/web/download.itexi}
419 This has nothing to do with the release, but it's a @qq{periodic
420 maintenance} task that might make sense to include with releases.
423 Send announcements to...
429 comp.os.linux.announce
438 info-lilypond@@gnu.org
440 linux-audio-announce@@lists.linuxaudio.org
441 linux-audio-user@@lists.linuxaudio.org
442 linux-audio-dev@@lists.linuxaudio.org
444 tex-music@@icking-music-archive.org
447 abcusers@@blackmill.net
449 rosegarden-user@@lists.sourceforge.net
451 noteedit-user@@berlios.de
453 gmane.comp.audio.fomus.devel
454 gmane.linux.audio.users
455 gmane.linux.audio.announce
456 gmane.comp.audio.rosegarden.devel
465 http://www.apple.com/downloads
466 harmony-central.com (news@@harmony-central.com)
467 versiontracker.com [auto]
470 https://savannah.gnu.org/news/submit.php?group_id=1673 @c => planet.gnu.org
476 @node Release extra notes
477 @section Release extra notes
479 @subsubheading Regenerating regression tests
481 Regenerating regtests (if the lilypond-book naming has changed):
486 git checkout release/lilypond-X.Y.Z-A
489 take lilypond-book and any related makefile updates from the
493 configure; make; make test
496 tar -cjf lilypond-X.Y.Z-A.test-output.tar.bz2 input/regression/out-test/
499 mv lilypond-X.Y.Z-A.test-output.tar.bz2 ../gub/regtests/
510 @subsubheading stable/2.12
512 If releasing stable/2.12, then:
517 apply doc patch: patches/rsync-lily.patch (or something like
521 change infodir in gub/specs/lilypond-doc.py from "lilypond.info"
522 to "lilypond-web.info"
525 @subsubheading Updating a release (changing a in x.y.z-a)
527 Really tentative instructions, almost certainly can be done
533 change the VERSION back to release you want. push change.
534 (hopefully you'll have forgotten to update it when you made your
538 make sure that there aren't any lilypond files floating around in
539 target/ (like usr/bin/lilypond).
542 build the specific package(s) you want, i.e.
545 bin/gub mingw::lilypond-installer
546 make LILYPOND_BRANCH=stable/2.12 -f lilypond.make doc
547 bin/gub --platform=darwin-x86 \
548 'git://git.sv.gnu.org/lilypond-doc.git?branch=stable/2.12'
553 build everything with the normal "make lilypond", then (maybe)
554 manually delete stuff you don't want to upload.
557 manually upload them. good luck figuring out the rsync
558 command(s). Hints are in test-lily/
562 run the normal lilypond-upload command, and (maybe) manually
563 delete stuff you didn't want to upload from the server.
567 @node Notes on builds with GUB
568 @section Notes on builds with GUB
570 @subsubheading Building GUB
572 GUB - the Grand Unified Builder - is used to build the release
573 versions of LilyPond. For background information, see
574 @ref{Grand Unified Builder (GUB)}. The simplest way to set up a
575 GUB build environment is to use a virtual machine with LilyDev
576 (@ref{LilyDev}). Follow the instructions on that page to set this
577 up. Make sure that your virtual machine has enough disk space -
578 a GUB installation takes over 30 GBytes of disk space, and if you
579 allocate too little, it will fail during the setting up stage and
580 you will have to start again. 64 GBytes should be sufficient.
582 While GUB is being built, any interruptions are likely to make it
583 almost impossible to restart. If at all possible, leave the build
584 to continue uninterrupted.
586 Download GUB and start the set up:
589 git clone git://github.com/gperciva/gub/gub.git
594 This will take a very long time, even on a very fast computer.
595 You will need to be patient. It's also liable to fail - it
596 downloads a number of tools, and some will have moved and others
597 won't respond to the network. For example, the perl archive.
598 If this happens, download it from
599 @uref{http://www.cpan.org/src/5.0/perl-5.10.0.tar.gz}, saving the
600 archive to @file{gub/downloads/perl/}. Continue the set up with:
606 Once this has completed successfully, you can build the LilyPond
607 release package. However, this uses an archived version of the
608 regression tests, so it is better to download this first.
609 Download the test output from lilypond.org (you will need to
610 replace @code{2.15.33-1} with the latest build):
613 @uref{http://lilypond.org/download/binaries/test-output/lilypond-2.15.33-1.test-output.tar.bz2}
616 Copy the tarball into @file{gub/regtests/}, and tell the build
617 system that you have done this:
620 touch regtests/ignore
623 Now start the GUB build:
629 That's it. This will build LilyPond from current master. To build
630 the current unstable release, run:
633 make LILYPOND_BRANCH=release/unstable lilypond
636 The first time you do this, it will take a very long time.
638 Assuming the build has gone well, it can be uploaded using:
642 LILYPOND_BRANCH=release/unstable
643 LILYPOND_REPO_URL=git://git.sv.gnu.org/lilypond.git
646 @subsubheading Output files
648 GUB builds the files it needs into the directory
649 @code{gub/target/}. As a general rule, these don't need to be
650 touched unless there is a problem building GUB (see below).
651 The files to be uploaded are in @code{gub/uploads/}. Once the
652 build has completed successfully, there should be 8
653 installation files and 3 archives, totalling about 600MB.
654 There are also 4 directories:
663 @code{signatures} contains files that are used to track whether
664 some of the archives have already been built. Don't touch
667 @code{localdoc} probably contains local copies of the
670 @code{webdoc} contains the documentation to be uploaded.
672 @code{webtest} contains the regtest comparison, which should
673 be checked before upload, and is also uploaded for subsequent
676 The total upload is about 700 MB in total, and on an ADSL
677 connection will take about 4 hours to upload.
679 @subsubheading Subsequent builds
681 In principle, building the next release of LilyPond requires
682 no action other then following the instructions in
683 @ref{Minor release checklist}. Because much of the
684 infrastructure has already been built, it will take much less
685 time - about an hour on a fast computer.
687 Continuing to build LilyPond without any other
688 archiving/deletion of previous builds is likely to be successful,
689 but will take up a fair amount of disk space (around 2GB per
690 build) which may be a problem with a Virtual Machine. It's
691 therefore recommended to move (not copy) @code{gub/uploads} to
692 another machine/disk after each build, if space is at a premium.
694 However, if a significant change has been made to the LilyPond
695 source (e.g. added source files) the build may fail if tried on
696 top of a previous build. If this happens, be sure to
697 move/delete @code{gub/uploads} and all mentions of LilyPond
698 in @code{gub/target}. The latter can be achieved with this
702 rm -rf target/*/*/*lilypond*
705 Be @emph{very} careful with this command. Typing it wrongly
706 could wipe your disk completely.
708 @subsubheading Updating the web site
710 The @code{make lilypond-upload} command updates the documentation
711 on the LilyPond web site. However, it does @emph{not} update
712 any part of the site that is not part of the documentation - for
713 example, the front page (@code{index.html}). The website is
714 updated by 2 cron jobs running on the web server. One of these
715 pulls git master to the web server, and the other makes the
716 website with the standard @code{make website} command. They run
717 hourly, 30 minutes apart. So - to update the front page of the
718 website, it's necessary to update @code{VERSION} and
719 @code{news-front.itexi} in master and then wait for the cron
720 jobs to run. (N.B. - this is done by pushing the changes to
721 staging and letting patchy do its checks before it pushes to