X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Frelease-work.itexi;h=9120e6529ff1c225513026d21df7bd1a4e83cfd6;hb=528e1aac95928f3fbe017af0b3d7a0f0a0ccafbf;hp=baa68a85e468768c8defbf0d24412aaba1570134;hpb=8b77ad1750c202c78f4ea81844f7c93ef40aa400;p=lilypond.git diff --git a/Documentation/contributor/release-work.itexi b/Documentation/contributor/release-work.itexi index baa68a85e4..9120e6529f 100644 --- a/Documentation/contributor/release-work.itexi +++ b/Documentation/contributor/release-work.itexi @@ -7,6 +7,7 @@ * Minor release checklist:: * Major release checklist:: * Release extra notes:: +* Notes on builds with GUB:: @end menu @@ -74,22 +75,35 @@ A @qq{minor release} means an update of @code{y} in @code{2.x.y}. @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 -vi Documentation/web/news-front.itexi Documentation/web/news.itexi +git checkout release/unstable +git merge origin/master +make -C $LILYPOND_BUILD_DIR po-replace +mv $LILYPOND_BUILD_DIR/po/lilypond.pot po/ +gedit Documentation/web/news-front.itexi Documentation/web/news.itexi @end example @item Commit, push, switch back to master (or wherever else): @example +git commit -m "PO: update template." po/lilypond.pot git commit -m "Release: update news." Documentation/web/ git push origin HEAD:release/unstable git checkout master @@ -184,9 +198,10 @@ make lilypond-upload \ @enumerate -@item Switch back to master and get the updated news: +@item Update the current staging branch with the current news: @example +git fetch git checkout origin/staging git merge origin/release/unstable @end example @@ -214,6 +229,16 @@ git commit -m "Release: bump version." VERSION git push origin HEAD:staging @end example +If the push fails with a message like + +@example + ! [rejected] HEAD -> staging (non-fast-forward) +@end example + +@noindent +it means that somebody else updated the staging branch while you were +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: @@ -297,6 +322,14 @@ various websites, so be brief. @item Run convert-ly on all files, bump parser minimum version. +@item +Update lilypond.pot: + +@example +make -C $LILYPOND_BUILD_DIR po-replace +mv $LILYPOND_BUILD_DIR/po/lilypond.pot po/ +@end example + @item Make directories on lilypond.org: @@ -360,8 +393,8 @@ Disallow: /doc/v2.CURRENT-DEVELOPMENT/ @itemize @item -submit pots for translation: send url of tarball to -translation@@iro.umontreal.ca, mentioning lilypond-VERSION.pot +submit po template for translation: send url of tarball to +coordinator@@translationproject.org, mentioning lilypond-VERSION.pot @item update links to distros providing lilypond packages? link in: @@ -515,5 +548,159 @@ delete stuff you didn't want to upload from the server. @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).