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

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


@node Development phases
@section Development phases

There are 2.5 states of development for LilyPond.

@itemize

@item @strong{Stable phase}:
Starting from the release of a new major version @code{2.x.0}, the
following patches @strong{MAY NOT} be merged with master:

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

@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{Development phase}:
Any commits are fine.  Readers may be familiar with the term
@qq{merge window} from following Linux kernel news.


@item @strong{Release prep phase}:
FIXME: I don't like that name.

A new git branch @code{stable/2.x} is created, and a major release
is made in two weeks.

@itemize

@item @code{stable/2.x branch}:
Only translation updates and important bugfixes are allows.

@item @code{master}:
Normal @qq{stable phase} development occurs.

@end itemize

If we discover the need to change the syntax or build system, we
will apply it and re-start the release prep phase.

@end itemize

This marks a radical change from previous practice in LilyPond.
However, this setup is not intended to slow development -- as a
rule of thumb, the next development phase will start within a
month of somebody wanting to commit something which is not
permitted during the stable phase.



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

@example
git checkout release/unstable
@end example

@item
Get latest changes:

@example
git merge origin
@end example

@item
Make a release announcement by adding a news item, and moving the
oldest news item out of -front.

@example
Documentation/web/news-front.itexi
Documentation/web/news.itexi
@end example

@item (optional) Check that lilypond builds from scratch in an
out-of-tree build.

@item Upload release branch.

@example
git push origin
@end example

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

@item Build release on GUB by running:

@example
make lilypond
@end example

@noindent
or something like:

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

@item Check the regtest comparison in @file{uploads/webtest/} for
any unintentional breakage.

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

@end enumerate


@subheading Actual release

@enumerate

@item If you're not right user on the webserver, remove the "t"
from the rsync command in @file{test-lily/rsync-lily-doc.py} and
@file{test-lily/rsync-test.py}

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

@item Upload GUB by running:

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

@noindent
or something like:

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

@end enumerate


@subheading Post release

@enumerate

@item Switch back to master and get the updated news:

@example
git checkout master
git merge release/unstable
@end example

@item Update @file{VERSION} in lilypond git:

@example
VERSION = what you just did +0.0.1
DEVEL_VERSION = what you just did (i.e. is now online)
STABLE_VERSION = what's online
@end example

@item Push changes.

@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/web/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}.

Before release:

* write release notes. note: stringent size requirements for
 various websites, so be brief.

* write preface section for manual.

* submit pots for translation : send url of tarball to
translation@@iro.umontreal.ca, mentioning lilypond-VERSION.pot

* Check reg test

* Check all 2ly scripts.

* Run convert-ly on all files, bump parser minimum version.

* update links to distros providing lilypond packages?  link in
Documentation/web/download.itexi .  This has nothing to do with
the release, but I'm dumping this here so I'll find it when I
reorganize this list later.  -gp

* Make FTP directories on lilypond.org

* website:
  - Make new table in download.html

  - add to documentation list

  - revise examples tour.html/howto.html

  - add to front-page quick links

  - change all links to the stable documentation

  - doc auto redirects  to v2.LATEST-STABLE

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

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

News:

        comp.music.research
        comp.os.linux.announce

        comp.text.tex
        rec.music.compose

Mail:

        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

Web:

        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


@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


@node Administrative policies
@section Administrative policies

Not really release-specific notes, but I don't see enough material
here to make it a separate chapter, and the release person will
probably be the one taking care of this anyway.

@subsubheading Language-specific mailing lists

A translator can ask for an official lilypond-xy mailing list once
they've finished all @qq{priority 1} translation items.

@subsubheading Performing yearly copyright update (@qq{grand-replace})

At the start of each year, copyright notices for all source files
should be refreshed by running the following command from the top of
the source tree:

@example
make grand-replace
@end example

Internally, this invokes the script @file{scripts/build/grand-replace.py},
which performs a regular expression substitution for old-year -> new-year
wherever it finds a valid copyright notice.

Note that snapshots of third party files such as @file{texinfo.tex} should
not be included in the automatic update; @file{grand-replace.py} ignores these
files if they are listed in the variable @code{copied_files}.