* Minor release checklist::
* Major release checklist::
* Release extra notes::
+* Notes on builds with GUB::
@end menu
@enumerate
@item
-Switch to the release branch, get changes, prep release
-announcement. This requires a clean index and work tree. If the
-checkout displays modified files, you might want to run @code{git reset
---hard} before continuing.
+Using any system with git pull access (not necessarily the GUB
+build machine), use the commands below to switch to the release
+branch, get changes and prepare the release
+announcement. This requires a system which has the release/unstable
+branch. If you get a warning saying you are in @code{detached HEAD}
+state, then you should create a release/unstable branch with
+@code{git checkout release/unstable}.
+
+Check the environment variables are set as in
+@ref{Environment variables}.
+
+You need to ensure you have a clean index and work tree. If the
+checkout displays modified files, you might want to run
+@code{git reset --hard} before continuing.
@example
git fetch
-git checkout origin/release/unstable
-git merge origin
+git checkout release/unstable
+git merge origin/master
make -C $LILYPOND_BUILD_DIR po-replace
mv $LILYPOND_BUILD_DIR/po/lilypond.pot po/
-vi Documentation/web/news-front.itexi Documentation/web/news.itexi
+gedit Documentation/web/news-front.itexi Documentation/web/news.itexi
+gedit VERSION
@end example
+@itemize
+@item
+VERSION_DEVEL = the current development version (previous VERSION_DEVEL + 0.01)
+
+@item
+VERSION_STABLE = the current stable version (probably no change here)
+
+@end itemize
+
@item
Commit, push, switch back to master (or wherever else):
@example
+git commit -m "Release: bump VERSION_DEVEL." VERSION
git commit -m "PO: update template." po/lilypond.pot
git commit -m "Release: update news." Documentation/web/
git push origin HEAD:release/unstable
or something like:
@example
-make LILYPOND_BRANCH=stable/2.12 lilypond
+make LILYPOND_BRANCH=stable/2.16 lilypond
@end example
-@item Check the regtest comparison in @file{uploads/webtest/} for
+@item
+Check the regtest comparison in @file{uploads/webtest/} for
any unintentional breakage. More info in
@ref{Precompiled regression tests}.
-@item If any work was done on GUB since the last release, upload
+@item
+If any work was done on GUB since the last release, upload
binaries to a temporary location, ask for feedback, and wait a day
or two in case there's any major problems.
test-lily/rsync-test.py
@end example
-@code{graham} owns v2.13; @code{han-wen} owns v2.12.
-
@item Upload GUB by running:
@example
@enumerate
-@item Update the current staging branch with the current news:
+@item
+Update the current staging branch with the current news:
@example
git fetch
git merge origin/release/unstable
@end example
-@item Update @file{VERSION} in lilypond git and upload changes:
+@item
+Update @file{VERSION} in lilypond git and upload changes:
@example
-vi VERSION
+gedit VERSION
@end example
@itemize
@item
VERSION = what you just did +0.0.1
-
-@item
-DEVEL_VERSION = what you just did (i.e. is now online)
-
-@item
-STABLE_VERSION = what's online (probably no change here)
-
@end itemize
@example
-git commit -m "Release: bump version." VERSION
+git commit -m "Release: bump VERSION." VERSION
git push origin HEAD:staging
@end example
preparing your change. In that case, you need to restart the Post
Release process. Otherwise, proceed:
-@item (for now) do a @code{make doc} and manually upload:
-
-@example
-### upload-lily-web-media.sh
-#!/bin/sh
-BUILD_DIR=$HOME/src/build-lilypond
-
-PICS=$BUILD_DIR/Documentation/pictures/out-www/
-EXAMPLES=$BUILD_DIR/Documentation/ly-examples/out-www/
-
-cd $BUILD_DIR
-rsync -a $PICS graham@@lilypond.org:media/pictures
-rsync -a $EXAMPLES graham@@lilypond.org:media/ly-examples
-@end example
-
@item Wait a few hours for the website to update.
@item Email release notice to @code{info-lilypond}
@subheading Main requirements
-This is the current official guidelines.
+These are the current official guidelines.
@itemize
@item
@end example
@item
-Check for altered regtests, and document as necessary. (update
-numbers in the following command as appropriate)
+Check for altered regtests, and document as necessary:
@example
-git diff -u -r release/2.12.0-1 -r release/2.13.13-1 input/regression/
+git diff -u -r release/2.@var{FIRST-CURRENT-STABLE} \
+ -r release/2.@var{LAST-CURRENT-DEVELOPMENT} input/regression/
@end example
@end itemize
Make directories on lilypond.org:
@example
-~/web/download/sources/v2.14
-~/web/download/sources/v2.15
+~/download/sources/v2.@var{NEW-STABLE}
+~/download/sources/v2.@var{NEW-DEVELOPMENT}
@end example
@item
Shortly after the release, move all current contributors to
-previous contributors in:
+previous contributors in
+@file{Documentation/included/authors.itexi}.
-@example
-Documentation/included/authors.itexi
-@end example
-
-Also, delete old material in:
+@item
+Delete old material in @file{Documentation/changes.tely}, but
+don't forget to check it still compiles! Also update the version
+numbers:
@example
-Documentation/changes.tely
+@@node Top
+@@top New features in 2.@var{NEW-STABLE} since 2.@var{OLD-STABLE}
@end example
-but don't forget to check it still compiles! also update the
-version numbers.
-
@item
Website:
@itemize
@item
make a link from the old unstable to the next stable in
-lilypond.org's /doc/ dir. Keep all previous unstable->stable doc
-symlinks.
+lilypond.org's @file{/doc/} dir. Keep all previous unstable->stable
+doc symlinks.
Also, make the old docs self-contained -- if there's a redirect in
-/doc/v2.12/Documentation/index.html , replace it with the
-index.html.old-2.12 files.
+@file{/doc/v2.@var{OLD-STABLE}/Documentation/index.html} , replace it with the
+@file{index.html.old-2.@var{OLD-STABLE}} files.
The post-2.13 docs will need another way of handling the
self-containment. It won't be hard to whip up a python script
-that changes the link to ../../../../manuals.html to
-../website/manuals.html , but it's still a 30-minute task that
+that changes the link to @file{../../../../manuals.html} to
+@file{../website/manuals.html}, but it's still a 30-minute task that
needs to be done before 2.16.
@item
-doc auto redirects to v2.LATEST-STABLE
+doc auto redirects to @code{v2.@var{NEW-STABLE}}
@item
-add these two lines to http://www.lilypond.org/robots.txt:
+add these two lines to @file{Documentation/web/server/robots.txt}:
@example
-Disallow: /doc/v2.PREVIOUS-STABLE/
-Disallow: /doc/v2.CURRENT-DEVELOPMENT/
+Disallow: /doc/v2.@var{OLD-STABLE}/
+Disallow: /doc/v2.@var{NEW-DEVELOPMENT}/
@end example
@end itemize
@itemize
@item
submit po template for translation: send url of tarball to
-coordinator@@translationproject.org, mentioning lilypond-VERSION.pot
+@email{coordinator@@translationproject.org}, mentioning
+lilypond-VERSION.pot
@item
update links to distros providing lilypond packages? link in:
@file{Documentation/web/download.itexi}
-This has nothing to do with the release, but it's a "periodic
-maintenance" task that might make sense to include with releases.
+This has nothing to do with the release, but it's a @qq{periodic
+maintenance} task that might make sense to include with releases.
@item
Send announcements to...
@end enumerate
+@node Notes on builds with GUB
+@section Notes on builds with GUB
+@subsubheading Building GUB
+
+GUB - the Grand Unified Builder - is used to build the release
+versions of LilyPond. For background information, see
+@ref{Grand Unified Builder (GUB)}. The simplest way to set up a
+GUB build environment is to use a virtual machine with LilyDev
+(@ref{LilyDev}). Follow the instructions on that page to set this
+up. Make sure that your virtual machine has enough disk space -
+a GUB installation takes over 30 GBytes of disk space, and if you
+allocate too little, it will fail during the setting up stage and
+you will have to start again. 64 GBytes should be sufficient.
+
+While GUB is being built, any interruptions are likely to make it
+almost impossible to restart. If at all possible, leave the build
+to continue uninterrupted.
+
+Download GUB and start the set up:
+
+@example
+git clone git://github.com/gperciva/gub/gub.git
+cd gub
+make bootstrap
+@end example
+
+This will take a very long time, even on a very fast computer.
+You will need to be patient. It's also liable to fail - it
+downloads a number of tools, and some will have moved and others
+won't respond to the network. For example, the perl archive.
+If this happens, download it from
+@uref{http://www.cpan.org/src/5.0/perl-5.10.0.tar.gz}, saving the
+archive to @file{gub/downloads/perl/}. Continue the set up with:
+
+@example
+make bootstrap
+@end example
+
+Once this has completed successfully, you can build the LilyPond
+release package. However, this uses an archived version of the
+regression tests, so it is better to download this first.
+Download the test output from lilypond.org (you will need to
+replace @code{2.15.33-1} with the latest build):
+
+@smallexample
+@uref{http://lilypond.org/download/binaries/test-output/lilypond-2.15.33-1.test-output.tar.bz2}
+@end smallexample
+
+Copy the tarball into @file{gub/regtests/}, and tell the build
+system that you have done this:
+
+@example
+touch regtests/ignore
+@end example
+
+Now start the GUB build:
+
+@example
+make lilypond
+@end example
+
+That's it. This will build LilyPond from current master. To build
+the current unstable release, run:
+
+@example
+make LILYPOND_BRANCH=release/unstable lilypond
+@end example
+
+The first time you do this, it will take a very long time.
+
+Assuming the build has gone well, it can be uploaded using:
+
+@example
+make lilypond-upload
+ LILYPOND_BRANCH=release/unstable
+ LILYPOND_REPO_URL=git://git.sv.gnu.org/lilypond.git
+@end example
+
+@subsubheading Output files
+
+GUB builds the files it needs into the directory
+@code{gub/target/}. As a general rule, these don't need to be
+touched unless there is a problem building GUB (see below).
+The files to be uploaded are in @code{gub/uploads/}. Once the
+build has completed successfully, there should be 8
+installation files and 3 archives, totalling about 600MB.
+There are also 4 directories:
+
+@example
+gub/signatures
+gub/localdoc
+gub/webdoc
+gub/webtest
+@end example
+
+@code{signatures} contains files that are used to track whether
+some of the archives have already been built. Don't touch
+these.
+
+@code{localdoc} probably contains local copies of the
+documentation.
+
+@code{webdoc} contains the documentation to be uploaded.
+
+@code{webtest} contains the regtest comparison, which should
+be checked before upload, and is also uploaded for subsequent
+checking.
+
+The total upload is about 700 MB in total, and on an ADSL
+connection will take about 4 hours to upload.
+
+@subsubheading Subsequent builds
+
+In principle, building the next release of LilyPond requires
+no action other then following the instructions in
+@ref{Minor release checklist}. Because much of the
+infrastructure has already been built, it will take much less
+time - about an hour on a fast computer.
+
+Continuing to build LilyPond without any other
+archiving/deletion of previous builds is likely to be successful,
+but will take up a fair amount of disk space (around 2GB per
+build) which may be a problem with a Virtual Machine. It's
+therefore recommended to move (not copy) @code{gub/uploads} to
+another machine/disk after each build, if space is at a premium.
+
+However, if a significant change has been made to the LilyPond
+source (e.g. added source files) the build may fail if tried on
+top of a previous build. If this happens, be sure to
+move/delete @code{gub/uploads} and all mentions of LilyPond
+in @code{gub/target}. The latter can be achieved with this
+command:
+
+@example
+rm -rf target/*/*/*lilypond*
+@end example
+Be @emph{very} careful with this command. Typing it wrongly
+could wipe your disk completely.
+
+@subsubheading Updating the web site
+
+The @code{make lilypond-upload} command updates the documentation
+on the LilyPond web site. However, it does @emph{not} update
+any part of the site that is not part of the documentation - for
+example, the front page (@code{index.html}). The website is
+updated by 2 cron jobs running on the web server. One of these
+pulls git master to the web server, and the other makes the
+website with the standard @code{make website} command. They run
+hourly, 30 minutes apart. So - to update the front page of the
+website, it's necessary to update @code{VERSION} and
+@code{news-front.itexi} in master and then wait for the cron
+jobs to run. (N.B. - this is done by pushing the changes to
+staging and letting patchy do its checks before it pushes to
+master).
projects / lilypond.git / blobdiff