CG: Add LILYPOND_BUILD_DIR environment variable, fix issues 2604 and 2524.

[lilypond.git] / Documentation / contributor / release-work.itexi

@c -*- coding: utf-8; mode: texinfo; -*-
@node Release work
@chapter Release work

@menu
* Development phases::
* Minor release checklist::
* Major release checklist::
* Release extra notes::
@end menu


@node Development phases
@section Development phases

There are 2 states of development on @code{master}:

@enumerate

@item @strong{Normal development}:
Any commits are fine.

@item @strong{Build-frozen}:
Do not require any additional or updated libraries or make
non-trivial changes to the build process.  Any such patch (or
branch) may not be merged with master during this period.

This should occur approximately 1 month before any alpha version
of the next stable release, and ends when the next unstable branch
begins.

@end enumerate


After announcing a beta release, branch @code{stable/2.x}.  There
are 2 states of development for this branch:

@enumerate
@item @strong{Normal maintenance}:
The following patches @strong{MAY NOT} be merged with this branch:

@itemize
@item Any change to the input syntax.  If a file compiled with a
previous @code{2.x} (beta) version, then it must compile in the
new version.

Exception: any bugfix to a Critical issue.

@item New features with new syntax @emph{may be committed},
although once committed that syntax cannot change during the
remainder of the stable phase.

@item Any change to the build dependencies (including programming
libraries, documentation process programs, or python modules used
in the buildscripts).  If a contributor could compile a previous
lilypond @code{2.x}, then he must be able to compile the new
version.

@end itemize

@item @strong{Release prep}:
Only translation updates and important bugfixes are allowed.

@end enumerate


@node Minor release checklist
@section Minor release checklist

A @qq{minor release} means an update of @code{y} in @code{2.x.y}.

@subheading Pre-release

@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.

@example
git fetch
git checkout origin/release/unstable
git merge origin
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
@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
@end example

@item
If you do not have the previous release test-output tarball, download
it and put it in @code{regtests/}

@item Prepare GUB environment by running:

@example
### my-gub.sh
# special terminal, and default PATH environment.
# import these special environment vars:
#   HOME, HTTP_PROXY, TERM
env -i \
  HOME=$HOME \
  HTTP_PROXY=$HTTP_PROXY \
  bash --rcfile my-bashrc
@end example

@example
### my-bashrc
export PS1="\[\e[1;33mGUB-ENV \w\]$ \[\e[0m\]"
export PATH=$PATH
export TERM=xterm
@end example


@item Build release on GUB by running:

@example
make LILYPOND_BRANCH=release/unstable lilypond
@end example

@noindent
or something like:

@example
make LILYPOND_BRANCH=stable/2.12 lilypond
@end example

@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
binaries to a temporary location, ask for feedback, and wait a day
or two in case there's any major problems.

@warning{Always do this for a stable release.}

@end enumerate


@subheading Actual release

@enumerate

@item If you're not the right user on the webserver, remove the
@code{t} from the rsync command in:

@example
test-lily/rsync-lily-doc.py
test-lily/rsync-test.py
@end example

@code{graham} owns v2.13; @code{han-wen} owns v2.12.

@item Upload GUB by running:

@example
make lilypond-upload \
  LILYPOND_REPO_URL=git://git.sv.gnu.org/lilypond.git \
  LILYPOND_BRANCH=release/unstable
@end example

@noindent
or something like:

@example
make lilypond-upload \
  LILYPOND_REPO_URL=git://git.sv.gnu.org/lilypond.git \
  LILYPOND_BRANCH=stable/2.12
@end example

@end enumerate


@subheading Post release

@enumerate

@item Update the current staging branch with the current news:

@example
git fetch
git checkout origin/staging
git merge origin/release/unstable
@end example

@item Update @file{VERSION} in lilypond git and upload changes:

@example
vi 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 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:

@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}

@end enumerate



@node Major release checklist
@section Major release checklist

A @qq{major release} means an update of @code{x} in @code{2.x.0}.

@subheading Main requirements

This is the current official guidelines.

@itemize
@item
0 Critical issues for two weeks (14 days) after the latest release
candidate.

@end itemize


@subheading Potential requirements

These might become official guidelines in the future.

@itemize
@item
Check reg test

@item
Check all 2ly scripts

@item
Check for emergencies the docs:

@example
grep FIXME --exclude "misc/*" --exclude "*GNUmakefile" \
  --exclude "snippets/*" ????*/*
@end example

@item
Check for altered regtests, and document as necessary.  (update
numbers in the following command as appropriate)

@example
git diff -u -r release/2.12.0-1 -r release/2.13.13-1 input/regression/
@end example

@end itemize


@subheading Housekeeping requirements

Before the release:

@itemize
@item
write release notes.  note: stringent size requirements for
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:

@example
~/web/download/sources/v2.14
~/web/download/sources/v2.15
@end example

@item
Shortly after the release, move all current contributors to
previous contributors in:

@example
Documentation/included/authors.itexi
@end example

Also, delete old material in:

@example
Documentation/changes.tely
@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.

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.

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
needs to be done before 2.16.

@item
doc auto redirects  to v2.LATEST-STABLE

@item
add these two lines to http://www.lilypond.org/robots.txt:

@example
Disallow: /doc/v2.PREVIOUS-STABLE/
Disallow: /doc/v2.CURRENT-DEVELOPMENT/
@end example

@end itemize

@end itemize

@subheading Unsorted

@itemize
@item
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:
@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.

@item
Send announcements to...

News:

@example
comp.music.research
comp.os.linux.announce

comp.text.tex
rec.music.compose
@end example

Mail:

@example
info-lilypond@@gnu.org

linux-audio-announce@@lists.linuxaudio.org
linux-audio-user@@lists.linuxaudio.org
linux-audio-dev@@lists.linuxaudio.org

tex-music@@icking-music-archive.org

--- non-existant?
abcusers@@blackmill.net

rosegarden-user@@lists.sourceforge.net
info-gnu@@gnu.org
noteedit-user@@berlios.de

gmane.comp.audio.fomus.devel
gmane.linux.audio.users
gmane.linux.audio.announce
gmane.comp.audio.rosegarden.devel
@end example

Web:

@example
lilypond.org
freshmeat.net
linuxfr.com
http://www.apple.com/downloads
harmony-central.com (news@@harmony-central.com)
versiontracker.com [auto]
hitsquad.com [auto]
http://www.svgx.org
https://savannah.gnu.org/news/submit.php?group_id=1673  @c => planet.gnu.org
@end example

@end itemize


@node Release extra notes
@section Release extra notes

@subsubheading Regenerating regression tests

Regenerating regtests (if the lilypond-book naming has changed):

@itemize

@item
git checkout release/lilypond-X.Y.Z-A

@item
take lilypond-book and any related makefile updates from the
latest git.

@item
configure; make; make test

@item
tar -cjf lilypond-X.Y.Z-A.test-output.tar.bz2 input/regression/out-test/

@item
mv lilypond-X.Y.Z-A.test-output.tar.bz2 ../gub/regtests/

@item
cd ../gub/regtests/

@item
make lilypond

@end itemize


@subsubheading stable/2.12

If releasing stable/2.12, then:

@itemize

@item
apply doc patch: patches/rsync-lily.patch  (or something like
that)

@item
change infodir in gub/specs/lilypond-doc.py from "lilypond.info"
to "lilypond-web.info"
@end itemize

@subsubheading Updating a release (changing a in x.y.z-a)

Really tentative instructions, almost certainly can be done
better.

@enumerate

@item
change the VERSION back to release you want.  push change.
(hopefully you'll have forgotten to update it when you made your
last release)

@item
make sure that there aren't any lilypond files floating around in
target/  (like usr/bin/lilypond).

@item
build the specific package(s) you want, i.e.

@example
bin/gub mingw::lilypond-installer
make LILYPOND_BRANCH=stable/2.12 -f lilypond.make doc
bin/gub --platform=darwin-x86 \
  'git://git.sv.gnu.org/lilypond-doc.git?branch=stable/2.12'
@end example

or

build everything with the normal "make lilypond", then (maybe)
manually delete stuff you don't want to upload.

@item
manually upload them.  good luck figuring out the rsync
command(s).  Hints are in test-lily/

or

run the normal lilypond-upload command, and (maybe) manually
delete stuff you didn't want to upload from the server.

@end enumerate