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 Don't forget to prepare the GUB build machine by deleting and moving unneeded
79 files: see @qq{Subsequent builds} in @ref{Notes on builds with GUB}.
82 Using any system with git pull access (not necessarily the GUB
83 build machine), use the commands below to do the following:
87 switch to the release branch
90 update the release branch from origin/master
93 update the translation files
96 create the release announcement
99 update the build versions.
103 VERSION_DEVEL = the current development version (previous VERSION_DEVEL + 0.01)
106 VERSION_STABLE = the current stable version (probably no change here)
111 update the @qq{Welcome to LilyPond} version numbers to the version about to be
116 This requires a system which has the release/unstable
117 branch. If you get a warning saying you are in @code{detached HEAD}
118 state, then you should create a release/unstable branch with
119 @code{git checkout release/unstable}.
121 Check the environment variables are set as in
122 @ref{Environment variables}.
124 You need to ensure you have a clean index and work tree. If the
125 checkout displays modified files, you might want to run
126 @code{git reset --hard} before continuing.
130 git checkout release/unstable
131 git merge origin/master
132 make -C $LILYPOND_BUILD_DIR po-replace
133 mv $LILYPOND_BUILD_DIR/po/lilypond.pot po/
134 gedit Documentation/web/news-new.itexi Documentation/web/news-old.itexi
135 gedit Documentation/web/news-headlines.itexi
140 Editing the @file{news-headlines.itexi} file is a bit tricky, since it contains
141 URLs with escaped characters. An example of what is needed is that releasing
142 @code{2.19.50} after the release of @code{2.19.49} needed the line:
145 @@uref@{news.html#LilyPond-2_002e19_002e49-released-October-16_002c-2016,
146 LilyPond 2.19.49 released - @@emph@{October 16, 2016@}@}
152 @@uref@{news.html#LilyPond-2_002e19_002e50-released-November-6_002c-2016,
153 LilyPond 2.19.50 released - @@emph@{November 6, 2016@}@}
156 Don't forget to update the entry above that line to show the latest release
160 Commit, push, switch back to master (or wherever else):
163 git commit -m "Release: bump VERSION_DEVEL." VERSION
164 git commit -m "PO: update template." po/lilypond.pot
165 git commit -m "Release: update news." Documentation/web/
166 git commit -m "Release: bump Welcome versions." ly/Wel*.ly
167 git push origin HEAD:release/unstable
172 If you do not have the previous release test-output tarball, download
173 it and put it in @code{regtests/}
175 @item Prepare GUB environment by running:
179 # special terminal, and default PATH environment.
180 # import these special environment vars:
181 # HOME, HTTP_PROXY, TERM
184 HTTP_PROXY=$HTTP_PROXY \
185 bash --rcfile my-bashrc
190 export PS1="\[\e[1;33mGUB-ENV \w\]$ \[\e[0m\]"
196 @item Build release on GUB by running:
199 make LILYPOND_BRANCH=release/unstable lilypond
206 make LILYPOND_BRANCH=stable/2.16 lilypond
210 Check the regtest comparison in @file{uploads/webtest/} for
211 any unintentional breakage. More info in
212 @ref{Precompiled regression tests}.
215 If any work was done on GUB since the last release, upload
216 binaries to a temporary location, ask for feedback, and wait a day
217 or two in case there's any major problems.
219 @warning{Always do this for a stable release.}
224 @subheading Actual release
228 @item If you're not the right user on the webserver, remove the
229 @code{t} from the rsync command in:
232 test-lily/rsync-lily-doc.py
233 test-lily/rsync-test.py
236 @item Upload GUB by running:
239 make lilypond-upload \
240 LILYPOND_REPO_URL=git://git.sv.gnu.org/lilypond.git \
241 LILYPOND_BRANCH=release/unstable
248 make lilypond-upload \
249 LILYPOND_REPO_URL=git://git.sv.gnu.org/lilypond.git \
250 LILYPOND_BRANCH=stable/2.12
256 @subheading Post release
261 Update the current staging branch with the current news:
265 git checkout origin/staging
266 git merge origin/release/unstable
270 Update @file{VERSION} in lilypond git and upload changes:
278 VERSION = what you just did +0.0.1
282 git commit -m "Release: bump VERSION." VERSION
283 git push origin HEAD:staging
286 If the push fails with a message like
289 ! [rejected] HEAD -> staging (non-fast-forward)
293 it means that somebody else updated the staging branch while you were
294 preparing your change. In that case, you need to restart the Post
295 Release process. Otherwise, proceed:
297 @item Wait a few hours for the website to update.
299 @item Email release notice to @code{info-lilypond}
305 @node Major release checklist
306 @section Major release checklist
308 A @qq{major release} means an update of @code{x} in @code{2.x.0}.
310 @subheading Main requirements
312 These are the current official guidelines.
316 0 Critical issues for two weeks (14 days) after the latest release
322 @subheading Potential requirements
324 These might become official guidelines in the future.
331 Check all 2ly scripts
334 Check for emergencies the docs:
337 grep FIXME --exclude "misc/*" --exclude "*GNUmakefile" \
338 --exclude "snippets/*" ????*/*
342 Check for altered regtests, and document as necessary:
345 git diff -u -r release/2.@var{FIRST-CURRENT-STABLE} \
346 -r release/2.@var{LAST-CURRENT-DEVELOPMENT} input/regression/
352 @subheading Housekeeping requirements
358 write release notes. note: stringent size requirements for
359 various websites, so be brief.
362 Run convert-ly on all files, bump parser minimum version.
368 make -C $LILYPOND_BUILD_DIR po-replace
369 mv $LILYPOND_BUILD_DIR/po/lilypond.pot po/
373 Make directories on lilypond.org:
376 ~/download/sources/v2.@var{NEW-STABLE}
377 ~/download/sources/v2.@var{NEW-DEVELOPMENT}
381 Shortly after the release, move all current contributors to
382 previous contributors in
383 @file{Documentation/included/authors.itexi}.
386 Delete old material in @file{Documentation/changes.tely}, but
387 don't forget to check it still compiles! Also update the version
392 @@top New features in 2.@var{NEW-STABLE} since 2.@var{OLD-STABLE}
400 make a link from the old unstable to the next stable in
401 lilypond.org's @file{/doc/} dir. Keep all previous unstable->stable
404 Also, make the old docs self-contained -- if there's a redirect in
405 @file{/doc/v2.@var{OLD-STABLE}/Documentation/index.html} , replace it with the
406 @file{index.html.old-2.@var{OLD-STABLE}} files.
408 The post-2.13 docs will need another way of handling the
409 self-containment. It won't be hard to whip up a python script
410 that changes the link to @file{../../../../manuals.html} to
411 @file{../website/manuals.html}, but it's still a 30-minute task that
412 needs to be done before 2.16.
415 doc auto redirects to @code{v2.@var{NEW-STABLE}}
418 add these two lines to @file{Documentation/web/server/robots.txt}:
421 Disallow: /doc/v2.@var{OLD-STABLE}/
422 Disallow: /doc/v2.@var{NEW-DEVELOPMENT}/
433 submit po template for translation: send url of tarball to
434 @email{coordinator@@translationproject.org}, mentioning
438 update links to distros providing lilypond packages? link in:
439 @file{Documentation/web/download.itexi}
441 This has nothing to do with the release, but it's a @qq{periodic
442 maintenance} task that might make sense to include with releases.
445 Send announcements to...
451 comp.os.linux.announce
460 info-lilypond@@gnu.org
462 linux-audio-announce@@lists.linuxaudio.org
463 linux-audio-user@@lists.linuxaudio.org
464 linux-audio-dev@@lists.linuxaudio.org
466 tex-music@@icking-music-archive.org
469 abcusers@@blackmill.net
471 rosegarden-user@@lists.sourceforge.net
473 noteedit-user@@berlios.de
475 gmane.comp.audio.fomus.devel
476 gmane.linux.audio.users
477 gmane.linux.audio.announce
478 gmane.comp.audio.rosegarden.devel
487 http://www.apple.com/downloads
488 harmony-central.com (news@@harmony-central.com)
489 versiontracker.com [auto]
491 https://savannah.gnu.org/news/submit.php?group_id=1673 @c => planet.gnu.org
497 @node Release extra notes
498 @section Release extra notes
500 @subsubheading Regenerating regression tests
502 Regenerating regtests (if the lilypond-book naming has changed):
507 git checkout release/lilypond-X.Y.Z-A
510 take lilypond-book and any related makefile updates from the
514 configure; make; make test
517 tar -cjf lilypond-X.Y.Z-A.test-output.tar.bz2 input/regression/out-test/
520 mv lilypond-X.Y.Z-A.test-output.tar.bz2 ../gub/regtests/
531 @subsubheading stable/2.12
533 If releasing stable/2.12, then:
538 apply doc patch: patches/rsync-lily.patch (or something like
542 change infodir in gub/specs/lilypond-doc.py from "lilypond.info"
543 to "lilypond-web.info"
546 @subsubheading Updating a release (changing a in x.y.z-a)
548 Really tentative instructions, almost certainly can be done
554 change the VERSION back to release you want. push change.
555 (hopefully you'll have forgotten to update it when you made your
559 make sure that there aren't any lilypond files floating around in
560 target/ (like usr/bin/lilypond).
563 build the specific package(s) you want, i.e.
566 bin/gub mingw::lilypond-installer
567 make LILYPOND_BRANCH=stable/2.12 -f lilypond.make doc
568 bin/gub --platform=darwin-x86 \
569 'git://git.sv.gnu.org/lilypond-doc.git?branch=stable/2.12'
574 build everything with the normal "make lilypond", then (maybe)
575 manually delete stuff you don't want to upload.
578 manually upload them. good luck figuring out the rsync
579 command(s). Hints are in test-lily/
583 run the normal lilypond-upload command, and (maybe) manually
584 delete stuff you didn't want to upload from the server.
588 @node Notes on builds with GUB
589 @section Notes on builds with GUB
591 @subsubheading Building GUB
593 GUB - the Grand Unified Builder - is used to build the release
594 versions of LilyPond. For background information, see
595 @ref{Grand Unified Builder (GUB)}. The simplest way to set up a
596 GUB build environment is to use a virtual machine with LilyDev
597 (@ref{LilyDev}). Follow the instructions on that page to set this
598 up. Make sure that your virtual machine has enough disk space -
599 a GUB installation takes over 30 GBytes of disk space, and if you
600 allocate too little, it will fail during the setting up stage and
601 you will have to start again. 64 GBytes should be sufficient.
603 While GUB is being built, any interruptions are likely to make it
604 almost impossible to restart. If at all possible, leave the build
605 to continue uninterrupted.
607 Download GUB and start the set up:
610 git clone git://github.com/gperciva/gub.git
615 This will take a very long time, even on a very fast computer.
616 You will need to be patient. It's also liable to fail - it
617 downloads a number of tools, and some will have moved and others
618 won't respond to the network. For example, the perl archive.
619 If this happens, download it from
620 @uref{http://www.cpan.org/src/5.0/perl-5.10.0.tar.gz}, saving the
621 archive to @file{gub/downloads/perl/}. Continue the set up with:
627 Once this has completed successfully, you can build the LilyPond
628 release package. However, this uses an archived version of the
629 regression tests, so it is better to download this first.
630 Download the test output from lilypond.org (you will need to
631 replace @code{2.15.33-1} with the latest build):
634 @uref{http://lilypond.org/downloads/binaries/test-output/lilypond-2.15.33-1.test-output.tar.bz2}
637 Copy the tarball into @file{regtests/}, and tell the build system that
641 touch regtests/ignore
644 Now start the GUB build:
650 That's it. This will build LilyPond from current master. To build
651 the current unstable release, run:
654 make LILYPOND_BRANCH=release/unstable lilypond
657 The first time you do this, it will take a very long time.
659 Assuming the build has gone well, it can be uploaded using:
663 LILYPOND_BRANCH=release/unstable
664 LILYPOND_REPO_URL=git://git.sv.gnu.org/lilypond.git
667 @subsubheading Output files
669 GUB builds the files it needs into the directory
670 @code{gub/target/}. As a general rule, these don't need to be
671 touched unless there is a problem building GUB (see below).
672 The files to be uploaded are in @code{gub/uploads/}. Once the
673 build has completed successfully, there should be 8
674 installation files and 3 archives, totalling about 600MB.
675 There are also 4 directories:
684 @code{signatures} contains files that are used to track whether
685 some of the archives have already been built. Don't touch
688 @code{localdoc} probably contains local copies of the
691 @code{webdoc} contains the documentation to be uploaded.
693 @code{webtest} contains the regtest comparison, which should
694 be checked before upload, and is also uploaded for subsequent
697 The total upload is about 700 MB in total, and on an ADSL
698 connection will take about 4 hours to upload.
700 @subsubheading Subsequent builds
702 In principle, building the next release of LilyPond requires
703 no action other then following the instructions in
704 @ref{Minor release checklist}. Because much of the
705 infrastructure has already been built, it will take much less
706 time - about an hour on a fast computer.
708 Continuing to build LilyPond without any other
709 archiving/deletion of previous builds is likely to be successful,
710 but will take up a fair amount of disk space (around 2GB per
711 build) which may be a problem with a Virtual Machine. It's
712 therefore recommended to move (not copy) @code{gub/uploads} to
713 another machine/disk after each build, if space is at a premium.
715 However, if a significant change has been made to the LilyPond
716 source (e.g. added source files) the build may fail if tried on
717 top of a previous build. If this happens, be sure to
718 move/delete @code{gub/uploads} and all mentions of LilyPond
719 in @code{gub/target}. The latter can be achieved with this
723 rm -rf target/*/*/*lilypond*
726 Be @emph{very} careful with this command. Typing it wrongly
727 could wipe your disk completely.
729 @subsubheading Updating the web site
731 The @code{make lilypond-upload} command updates the documentation
732 on the LilyPond web site. However, it does @emph{not} update
733 any part of the site that is not part of the documentation - for
734 example, the front page (@code{index.html}). The website is
735 updated by 2 cron jobs running on the web server. One of these
736 pulls git master to the web server, and the other makes the
737 website with the standard @code{make website} command. They run
738 hourly, 30 minutes apart. So - to update the front page of the
739 website, it's necessary to update @code{VERSION} and
740 @code{news-headlines.itexi} in master and then wait for the cron
741 jobs to run. (N.B. - this is done by pushing the changes to
742 staging and letting patchy do its checks before it pushes to