@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}:
TODO: 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, get changes, prep release
announcement:

@example
git checkout release/unstable
git merge origin
vi Documentation/web/news-front.itexi Documentation/web/news.itexi
@end example

@item
Commit, push, switch back to master:

@example
git commit -m "Release: update news." Documentation/web/
git push origin
@end example

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

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

Note that this test uses the bounding boxes inside lilypond.
Errors in ghostscript don't generate differences inside lilypond,
so they are not registered in the regtest comparison.

@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=release/unstable 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 and upload changes:

@quotation
@quotation
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 quotation
@end quotation

@example
vi VERSION
git commit -m "Release: bump version." VERSION
git push origin
@end example


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

- happens when we have 0 Critical issues for two weeks (14 days).


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

  - make a link from the old unstable to the next stable in
    lilypond.org's /doc/ dir.  Keep all previous unstable->stable
    doc symlinks.

  - 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

- check for emergencies the docs:

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

- check for altered regtests, and document as necessary.  (update
  tags as appropriate)

@example
git diff -u -r release/2.12.0-1 -r release/2.13.13-1 input/regression/
@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}.