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
103 Commit, push, switch back to master (or wherever else):
106 git commit -m "PO: update template." po/lilypond.pot
107 git commit -m "Release: update news." Documentation/web/
108 git push origin HEAD:release/unstable
113 If you do not have the previous release test-output tarball, download
114 it and put it in @code{regtests/}
116 @item Prepare GUB environment by running:
120 # special terminal, and default PATH environment.
121 # import these special environment vars:
122 # HOME, HTTP_PROXY, TERM
125 HTTP_PROXY=$HTTP_PROXY \
126 bash --rcfile my-bashrc
131 export PS1="\[\e[1;33mGUB-ENV \w\]$ \[\e[0m\]"
137 @item Build release on GUB by running:
140 make LILYPOND_BRANCH=release/unstable lilypond
147 make LILYPOND_BRANCH=stable/2.12 lilypond
150 @item Check the regtest comparison in @file{uploads/webtest/} for
151 any unintentional breakage. More info in
152 @ref{Precompiled regression tests}.
154 @item If any work was done on GUB since the last release, upload
155 binaries to a temporary location, ask for feedback, and wait a day
156 or two in case there's any major problems.
158 @warning{Always do this for a stable release.}
163 @subheading Actual release
167 @item If you're not the right user on the webserver, remove the
168 @code{t} from the rsync command in:
171 test-lily/rsync-lily-doc.py
172 test-lily/rsync-test.py
175 @code{graham} owns v2.13; @code{han-wen} owns v2.12.
177 @item Upload GUB by running:
180 make lilypond-upload \
181 LILYPOND_REPO_URL=git://git.sv.gnu.org/lilypond.git \
182 LILYPOND_BRANCH=release/unstable
189 make lilypond-upload \
190 LILYPOND_REPO_URL=git://git.sv.gnu.org/lilypond.git \
191 LILYPOND_BRANCH=stable/2.12
197 @subheading Post release
201 @item Update the current staging branch with the current news:
205 git checkout origin/staging
206 git merge origin/release/unstable
209 @item Update @file{VERSION} in lilypond git and upload changes:
217 VERSION = what you just did +0.0.1
220 DEVEL_VERSION = what you just did (i.e. is now online)
223 STABLE_VERSION = what's online (probably no change here)
228 git commit -m "Release: bump version." VERSION
229 git push origin HEAD:staging
232 If the push fails with a message like
235 ! [rejected] HEAD -> staging (non-fast-forward)
239 it means that somebody else updated the staging branch while you were
240 preparing your change. In that case, you need to restart the Post
241 Release process. Otherwise, proceed:
243 @item (for now) do a @code{make doc} and manually upload:
246 ### upload-lily-web-media.sh
248 BUILD_DIR=$HOME/src/build-lilypond
250 PICS=$BUILD_DIR/Documentation/pictures/out-www/
251 EXAMPLES=$BUILD_DIR/Documentation/ly-examples/out-www/
254 rsync -a $PICS graham@@lilypond.org:media/pictures
255 rsync -a $EXAMPLES graham@@lilypond.org:media/ly-examples
258 @item Wait a few hours for the website to update.
260 @item Email release notice to @code{info-lilypond}
266 @node Major release checklist
267 @section Major release checklist
269 A @qq{major release} means an update of @code{x} in @code{2.x.0}.
271 @subheading Main requirements
273 This is the current official guidelines.
277 0 Critical issues for two weeks (14 days) after the latest release
283 @subheading Potential requirements
285 These might become official guidelines in the future.
292 Check all 2ly scripts
295 Check for emergencies the docs:
298 grep FIXME --exclude "misc/*" --exclude "*GNUmakefile" \
299 --exclude "snippets/*" ????*/*
303 Check for altered regtests, and document as necessary. (update
304 numbers in the following command as appropriate)
307 git diff -u -r release/2.12.0-1 -r release/2.13.13-1 input/regression/
313 @subheading Housekeeping requirements
319 write release notes. note: stringent size requirements for
320 various websites, so be brief.
323 Run convert-ly on all files, bump parser minimum version.
329 make -C $LILYPOND_BUILD_DIR po-replace
330 mv $LILYPOND_BUILD_DIR/po/lilypond.pot po/
334 Make directories on lilypond.org:
337 ~/web/download/sources/v2.14
338 ~/web/download/sources/v2.15
342 Shortly after the release, move all current contributors to
343 previous contributors in:
346 Documentation/included/authors.itexi
349 Also, delete old material in:
352 Documentation/changes.tely
355 but don't forget to check it still compiles! also update the
363 make a link from the old unstable to the next stable in
364 lilypond.org's /doc/ dir. Keep all previous unstable->stable doc
367 Also, make the old docs self-contained -- if there's a redirect in
368 /doc/v2.12/Documentation/index.html , replace it with the
369 index.html.old-2.12 files.
371 The post-2.13 docs will need another way of handling the
372 self-containment. It won't be hard to whip up a python script
373 that changes the link to ../../../../manuals.html to
374 ../website/manuals.html , but it's still a 30-minute task that
375 needs to be done before 2.16.
378 doc auto redirects to v2.LATEST-STABLE
381 add these two lines to http://www.lilypond.org/robots.txt:
384 Disallow: /doc/v2.PREVIOUS-STABLE/
385 Disallow: /doc/v2.CURRENT-DEVELOPMENT/
396 submit po template for translation: send url of tarball to
397 coordinator@@translationproject.org, mentioning lilypond-VERSION.pot
400 update links to distros providing lilypond packages? link in:
401 @file{Documentation/web/download.itexi}
403 This has nothing to do with the release, but it's a "periodic
404 maintenance" task that might make sense to include with releases.
407 Send announcements to...
413 comp.os.linux.announce
422 info-lilypond@@gnu.org
424 linux-audio-announce@@lists.linuxaudio.org
425 linux-audio-user@@lists.linuxaudio.org
426 linux-audio-dev@@lists.linuxaudio.org
428 tex-music@@icking-music-archive.org
431 abcusers@@blackmill.net
433 rosegarden-user@@lists.sourceforge.net
435 noteedit-user@@berlios.de
437 gmane.comp.audio.fomus.devel
438 gmane.linux.audio.users
439 gmane.linux.audio.announce
440 gmane.comp.audio.rosegarden.devel
449 http://www.apple.com/downloads
450 harmony-central.com (news@@harmony-central.com)
451 versiontracker.com [auto]
454 https://savannah.gnu.org/news/submit.php?group_id=1673 @c => planet.gnu.org
460 @node Release extra notes
461 @section Release extra notes
463 @subsubheading Regenerating regression tests
465 Regenerating regtests (if the lilypond-book naming has changed):
470 git checkout release/lilypond-X.Y.Z-A
473 take lilypond-book and any related makefile updates from the
477 configure; make; make test
480 tar -cjf lilypond-X.Y.Z-A.test-output.tar.bz2 input/regression/out-test/
483 mv lilypond-X.Y.Z-A.test-output.tar.bz2 ../gub/regtests/
494 @subsubheading stable/2.12
496 If releasing stable/2.12, then:
501 apply doc patch: patches/rsync-lily.patch (or something like
505 change infodir in gub/specs/lilypond-doc.py from "lilypond.info"
506 to "lilypond-web.info"
509 @subsubheading Updating a release (changing a in x.y.z-a)
511 Really tentative instructions, almost certainly can be done
517 change the VERSION back to release you want. push change.
518 (hopefully you'll have forgotten to update it when you made your
522 make sure that there aren't any lilypond files floating around in
523 target/ (like usr/bin/lilypond).
526 build the specific package(s) you want, i.e.
529 bin/gub mingw::lilypond-installer
530 make LILYPOND_BRANCH=stable/2.12 -f lilypond.make doc
531 bin/gub --platform=darwin-x86 \
532 'git://git.sv.gnu.org/lilypond-doc.git?branch=stable/2.12'
537 build everything with the normal "make lilypond", then (maybe)
538 manually delete stuff you don't want to upload.
541 manually upload them. good luck figuring out the rsync
542 command(s). Hints are in test-lily/
546 run the normal lilypond-upload command, and (maybe) manually
547 delete stuff you didn't want to upload from the server.
551 @node Notes on builds with GUB
552 @section Notes on builds with GUB
554 @subsubheading Building GUB
556 GUB - the Grand Unified Builder - is used to build the release
557 versions of LilyPond. For background information, see
558 @ref{Grand Unified Builder (GUB)}. The simplest way to set up a
559 GUB build environment is to use a virtual machine with LilyDev
560 (@ref{LilyDev}). Follow the instructions on that page to set this
561 up. Make sure that your virtual machine has enough disk space -
562 a GUB installation takes over 30 GBytes of disk space, and if you
563 allocate too little, it will fail during the setting up stage and
564 you will have to start again. 64 GBytes should be sufficient.
566 While GUB is being built, any interruptions are likely to make it
567 almost impossible to restart. If at all possible, leave the build
568 to continue uninterrupted.
570 Download GUB and start the set up:
573 git clone git://github.com/gperciva/gub/gub.git
578 This will take a very long time, even on a very fast computer.
579 You will need to be patient. It's also liable to fail - it
580 downloads a number of tools, and some will have moved and others
581 won't respond to the network. For example, the perl archive.
582 If this happens, download it from
583 @uref{http://www.cpan.org/src/5.0/perl-5.10.0.tar.gz}, saving the
584 archive to @file{gub/downloads/perl/}. Continue the set up with:
590 Once this has completed successfully, you can build the LilyPond
591 release package. However, this uses an archived version of the
592 regression tests, so it is better to download this first.
593 Download the test output from lilypond.org (you will need to
594 replace @code{2.15.33-1} with the latest build):
597 @uref{http://lilypond.org/download/binaries/test-output/lilypond-2.15.33-1.test-output.tar.bz2}
600 Copy the tarball into @file{gub/regtests/}, and tell the build
601 system that you have done this:
604 touch regtests/ignore
607 Now start the GUB build:
613 That's it. This will build LilyPond from current master. To build
614 the current unstable release, run:
617 make LILYPOND_BRANCH=release/unstable lilypond
620 The first time you do this, it will take a very long time.
622 Assuming the build has gone well, it can be uploaded using:
626 LILYPOND_BRANCH=release/unstable
627 LILYPOND_REPO_URL=git://git.sv.gnu.org/lilypond.git
630 @subsubheading Output files
632 GUB builds the files it needs into the directory
633 @code{gub/target/}. As a general rule, these don't need to be
634 touched unless there is a problem building GUB (see below).
635 The files to be uploaded are in @code{gub/uploads/}. Once the
636 build has completed successfully, there should be 8
637 installation files and 3 archives, totalling about 600MB.
638 There are also 4 directories:
647 @code{signatures} contains files that are used to track whether
648 some of the archives have already been built. Don't touch
651 @code{localdoc} probably contains local copies of the
654 @code{webdoc} contains the documentation to be uploaded.
656 @code{webtest} contains the regtest comparison, which should
657 be checked before upload, and is also uploaded for subsequent
660 The total upload is about 700 MB in total, and on an ADSL
661 connection will take about 4 hours to upload.
663 @subsubheading Subsequent builds
665 In principle, building the next release of LilyPond requires
666 no action other then following the instructions in
667 @ref{Minor release checklist}. Because much of the
668 infrastructure has already been built, it will take much less
669 time - about an hour on a fast computer.
671 Continuing to build LilyPond without any other
672 archiving/deletion of previous builds is likely to be successful,
673 but will take up a fair amount of disk space (around 2GB per
674 build) which may be a problem with a Virtual Machine. It's
675 therefore recommended to move (not copy) @code{gub/uploads} to
676 another machine/disk after each build, if space is at a premium.
678 However, if a significant change has been made to the LilyPond
679 source (e.g. added source files) the build may fail if tried on
680 top of a previous build. If this happens, be sure to
681 move/delete @code{gub/uploads} and all mentions of LilyPond
682 in @code{gub/target}. The latter can be achieved with this
686 rm -rf target/*/*/*lilypond*
689 Be @emph{very} careful with this command. Typing it wrongly
690 could wipe your disk completely.
692 @subsubheading Updating the web site
694 The @code{make lilypond-upload} command updates the documentation
695 on the LilyPond web site. However, it does @emph{not} update
696 any part of the site that is not part of the documentation - for
697 example, the front page (@code{index.html}). The website is
698 updated by 2 cron jobs running on the web server. One of these
699 pulls git master to the web server, and the other makes the
700 website with the standard @code{make website} command. They run
701 hourly, 30 minutes apart. So - to update the front page of the
702 website, it's necessary to update @code{VERSION} and
703 @code{news-front.itexi} in master and then wait for the cron
704 jobs to run. (N.B. - this is done by pushing the changes to
705 staging and letting patchy do its checks before it pushes to