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 Manually edit the two files @file{../ly/Welcome_to_LilyPond.ly} and
114 @file{../ly/Welcome-to-LilyPond-MacOS.ly} such that the hard coded
115 @code{\version} number reflects the version number about to be released.
118 Commit, push, switch back to master (or wherever else):
121 git commit -m "Release: bump VERSION_DEVEL." VERSION
122 git commit -m "Release: bump VERSION_DEVEL." ly/Welcome_to_LilyPond.ly
123 git commit -m "Release: bump VERSION_DEVEL." ly/Welcome-to-LilyPond-MacOS.ly
124 git commit -m "PO: update template." po/lilypond.pot
125 git commit -m "Release: update news." Documentation/web/
126 git push origin HEAD:release/unstable
131 If you do not have the previous release test-output tarball, download
132 it and put it in @code{regtests/}
134 @item Prepare GUB environment by running:
138 # special terminal, and default PATH environment.
139 # import these special environment vars:
140 # HOME, HTTP_PROXY, TERM
143 HTTP_PROXY=$HTTP_PROXY \
144 bash --rcfile my-bashrc
149 export PS1="\[\e[1;33mGUB-ENV \w\]$ \[\e[0m\]"
155 @item Build release on GUB by running:
158 make LILYPOND_BRANCH=release/unstable lilypond
165 make LILYPOND_BRANCH=stable/2.16 lilypond
169 Check the regtest comparison in @file{uploads/webtest/} for
170 any unintentional breakage. More info in
171 @ref{Precompiled regression tests}.
174 If any work was done on GUB since the last release, upload
175 binaries to a temporary location, ask for feedback, and wait a day
176 or two in case there's any major problems.
178 @warning{Always do this for a stable release.}
183 @subheading Actual release
187 @item If you're not the right user on the webserver, remove the
188 @code{t} from the rsync command in:
191 test-lily/rsync-lily-doc.py
192 test-lily/rsync-test.py
195 @item Upload GUB by running:
198 make lilypond-upload \
199 LILYPOND_REPO_URL=git://git.sv.gnu.org/lilypond.git \
200 LILYPOND_BRANCH=release/unstable
207 make lilypond-upload \
208 LILYPOND_REPO_URL=git://git.sv.gnu.org/lilypond.git \
209 LILYPOND_BRANCH=stable/2.12
215 @subheading Post release
220 Update the current staging branch with the current news:
224 git checkout origin/staging
225 git merge origin/release/unstable
229 Update @file{VERSION} in lilypond git and upload changes:
237 VERSION = what you just did +0.0.1
241 git commit -m "Release: bump VERSION." VERSION
242 git push origin HEAD:staging
245 If the push fails with a message like
248 ! [rejected] HEAD -> staging (non-fast-forward)
252 it means that somebody else updated the staging branch while you were
253 preparing your change. In that case, you need to restart the Post
254 Release process. Otherwise, proceed:
256 @item Wait a few hours for the website to update.
258 @item Email release notice to @code{info-lilypond}
264 @node Major release checklist
265 @section Major release checklist
267 A @qq{major release} means an update of @code{x} in @code{2.x.0}.
269 @subheading Main requirements
271 These are the current official guidelines.
275 0 Critical issues for two weeks (14 days) after the latest release
281 @subheading Potential requirements
283 These might become official guidelines in the future.
290 Check all 2ly scripts
293 Check for emergencies the docs:
296 grep FIXME --exclude "misc/*" --exclude "*GNUmakefile" \
297 --exclude "snippets/*" ????*/*
301 Check for altered regtests, and document as necessary:
304 git diff -u -r release/2.@var{FIRST-CURRENT-STABLE} \
305 -r release/2.@var{LAST-CURRENT-DEVELOPMENT} input/regression/
311 @subheading Housekeeping requirements
317 write release notes. note: stringent size requirements for
318 various websites, so be brief.
321 Run convert-ly on all files, bump parser minimum version.
327 make -C $LILYPOND_BUILD_DIR po-replace
328 mv $LILYPOND_BUILD_DIR/po/lilypond.pot po/
332 Make directories on lilypond.org:
335 ~/download/sources/v2.@var{NEW-STABLE}
336 ~/download/sources/v2.@var{NEW-DEVELOPMENT}
340 Shortly after the release, move all current contributors to
341 previous contributors in
342 @file{Documentation/included/authors.itexi}.
345 Delete old material in @file{Documentation/changes.tely}, but
346 don't forget to check it still compiles! Also update the version
351 @@top New features in 2.@var{NEW-STABLE} since 2.@var{OLD-STABLE}
359 make a link from the old unstable to the next stable in
360 lilypond.org's @file{/doc/} dir. Keep all previous unstable->stable
363 Also, make the old docs self-contained -- if there's a redirect in
364 @file{/doc/v2.@var{OLD-STABLE}/Documentation/index.html} , replace it with the
365 @file{index.html.old-2.@var{OLD-STABLE}} files.
367 The post-2.13 docs will need another way of handling the
368 self-containment. It won't be hard to whip up a python script
369 that changes the link to @file{../../../../manuals.html} to
370 @file{../website/manuals.html}, but it's still a 30-minute task that
371 needs to be done before 2.16.
374 doc auto redirects to @code{v2.@var{NEW-STABLE}}
377 add these two lines to @file{Documentation/web/server/robots.txt}:
380 Disallow: /doc/v2.@var{OLD-STABLE}/
381 Disallow: /doc/v2.@var{NEW-DEVELOPMENT}/
392 submit po template for translation: send url of tarball to
393 @email{coordinator@@translationproject.org}, mentioning
397 update links to distros providing lilypond packages? link in:
398 @file{Documentation/web/download.itexi}
400 This has nothing to do with the release, but it's a @qq{periodic
401 maintenance} task that might make sense to include with releases.
404 Send announcements to...
410 comp.os.linux.announce
419 info-lilypond@@gnu.org
421 linux-audio-announce@@lists.linuxaudio.org
422 linux-audio-user@@lists.linuxaudio.org
423 linux-audio-dev@@lists.linuxaudio.org
425 tex-music@@icking-music-archive.org
428 abcusers@@blackmill.net
430 rosegarden-user@@lists.sourceforge.net
432 noteedit-user@@berlios.de
434 gmane.comp.audio.fomus.devel
435 gmane.linux.audio.users
436 gmane.linux.audio.announce
437 gmane.comp.audio.rosegarden.devel
446 http://www.apple.com/downloads
447 harmony-central.com (news@@harmony-central.com)
448 versiontracker.com [auto]
451 https://savannah.gnu.org/news/submit.php?group_id=1673 @c => planet.gnu.org
457 @node Release extra notes
458 @section Release extra notes
460 @subsubheading Regenerating regression tests
462 Regenerating regtests (if the lilypond-book naming has changed):
467 git checkout release/lilypond-X.Y.Z-A
470 take lilypond-book and any related makefile updates from the
474 configure; make; make test
477 tar -cjf lilypond-X.Y.Z-A.test-output.tar.bz2 input/regression/out-test/
480 mv lilypond-X.Y.Z-A.test-output.tar.bz2 ../gub/regtests/
491 @subsubheading stable/2.12
493 If releasing stable/2.12, then:
498 apply doc patch: patches/rsync-lily.patch (or something like
502 change infodir in gub/specs/lilypond-doc.py from "lilypond.info"
503 to "lilypond-web.info"
506 @subsubheading Updating a release (changing a in x.y.z-a)
508 Really tentative instructions, almost certainly can be done
514 change the VERSION back to release you want. push change.
515 (hopefully you'll have forgotten to update it when you made your
519 make sure that there aren't any lilypond files floating around in
520 target/ (like usr/bin/lilypond).
523 build the specific package(s) you want, i.e.
526 bin/gub mingw::lilypond-installer
527 make LILYPOND_BRANCH=stable/2.12 -f lilypond.make doc
528 bin/gub --platform=darwin-x86 \
529 'git://git.sv.gnu.org/lilypond-doc.git?branch=stable/2.12'
534 build everything with the normal "make lilypond", then (maybe)
535 manually delete stuff you don't want to upload.
538 manually upload them. good luck figuring out the rsync
539 command(s). Hints are in test-lily/
543 run the normal lilypond-upload command, and (maybe) manually
544 delete stuff you didn't want to upload from the server.
548 @node Notes on builds with GUB
549 @section Notes on builds with GUB
551 @subsubheading Building GUB
553 GUB - the Grand Unified Builder - is used to build the release
554 versions of LilyPond. For background information, see
555 @ref{Grand Unified Builder (GUB)}. The simplest way to set up a
556 GUB build environment is to use a virtual machine with LilyDev
557 (@ref{LilyDev}). Follow the instructions on that page to set this
558 up. Make sure that your virtual machine has enough disk space -
559 a GUB installation takes over 30 GBytes of disk space, and if you
560 allocate too little, it will fail during the setting up stage and
561 you will have to start again. 64 GBytes should be sufficient.
563 While GUB is being built, any interruptions are likely to make it
564 almost impossible to restart. If at all possible, leave the build
565 to continue uninterrupted.
567 Download GUB and start the set up:
570 git clone git://github.com/gperciva/gub/gub.git
575 This will take a very long time, even on a very fast computer.
576 You will need to be patient. It's also liable to fail - it
577 downloads a number of tools, and some will have moved and others
578 won't respond to the network. For example, the perl archive.
579 If this happens, download it from
580 @uref{http://www.cpan.org/src/5.0/perl-5.10.0.tar.gz}, saving the
581 archive to @file{gub/downloads/perl/}. Continue the set up with:
587 Once this has completed successfully, you can build the LilyPond
588 release package. However, this uses an archived version of the
589 regression tests, so it is better to download this first.
590 Download the test output from lilypond.org (you will need to
591 replace @code{2.15.33-1} with the latest build):
594 @uref{http://lilypond.org/download/binaries/test-output/lilypond-2.15.33-1.test-output.tar.bz2}
597 Copy the tarball into @file{gub/regtests/}, and tell the build
598 system that you have done this:
601 touch regtests/ignore
604 Now start the GUB build:
610 That's it. This will build LilyPond from current master. To build
611 the current unstable release, run:
614 make LILYPOND_BRANCH=release/unstable lilypond
617 The first time you do this, it will take a very long time.
619 Assuming the build has gone well, it can be uploaded using:
623 LILYPOND_BRANCH=release/unstable
624 LILYPOND_REPO_URL=git://git.sv.gnu.org/lilypond.git
627 @subsubheading Output files
629 GUB builds the files it needs into the directory
630 @code{gub/target/}. As a general rule, these don't need to be
631 touched unless there is a problem building GUB (see below).
632 The files to be uploaded are in @code{gub/uploads/}. Once the
633 build has completed successfully, there should be 8
634 installation files and 3 archives, totalling about 600MB.
635 There are also 4 directories:
644 @code{signatures} contains files that are used to track whether
645 some of the archives have already been built. Don't touch
648 @code{localdoc} probably contains local copies of the
651 @code{webdoc} contains the documentation to be uploaded.
653 @code{webtest} contains the regtest comparison, which should
654 be checked before upload, and is also uploaded for subsequent
657 The total upload is about 700 MB in total, and on an ADSL
658 connection will take about 4 hours to upload.
660 @subsubheading Subsequent builds
662 In principle, building the next release of LilyPond requires
663 no action other then following the instructions in
664 @ref{Minor release checklist}. Because much of the
665 infrastructure has already been built, it will take much less
666 time - about an hour on a fast computer.
668 Continuing to build LilyPond without any other
669 archiving/deletion of previous builds is likely to be successful,
670 but will take up a fair amount of disk space (around 2GB per
671 build) which may be a problem with a Virtual Machine. It's
672 therefore recommended to move (not copy) @code{gub/uploads} to
673 another machine/disk after each build, if space is at a premium.
675 However, if a significant change has been made to the LilyPond
676 source (e.g. added source files) the build may fail if tried on
677 top of a previous build. If this happens, be sure to
678 move/delete @code{gub/uploads} and all mentions of LilyPond
679 in @code{gub/target}. The latter can be achieved with this
683 rm -rf target/*/*/*lilypond*
686 Be @emph{very} careful with this command. Typing it wrongly
687 could wipe your disk completely.
689 @subsubheading Updating the web site
691 The @code{make lilypond-upload} command updates the documentation
692 on the LilyPond web site. However, it does @emph{not} update
693 any part of the site that is not part of the documentation - for
694 example, the front page (@code{index.html}). The website is
695 updated by 2 cron jobs running on the web server. One of these
696 pulls git master to the web server, and the other makes the
697 website with the standard @code{make website} command. They run
698 hourly, 30 minutes apart. So - to update the front page of the
699 website, it's necessary to update @code{VERSION} and
700 @code{news-front.itexi} in master and then wait for the cron
701 jobs to run. (N.B. - this is done by pushing the changes to
702 staging and letting patchy do its checks before it pushes to