-@c -*- coding: us-ascii; mode: texinfo; -*-
+@c -*- coding: utf-8; mode: texinfo; -*-
@node Release work
@chapter Release work
@menu
-* Development phases::
-* Minor release checklist::
-* Major release checklist::
-* Release extra notes::
+* Development phases::
+* Minor release checklist::
+* Major release checklist::
+* Release extra notes::
@end menu
@node Development phases
@section Development phases
-There are 2.5 states of development for LilyPond.
+There are 2 states of development on @code{master}:
-@itemize
+@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:
-@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:
+@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} version, then it must compile in the new
-version.
+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
@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.
+@item @strong{Release prep}:
+Only translation updates and important bugfixes are allowed.
+@end enumerate
@node Minor release checklist
@enumerate
-@item Add a news item to @file{Documentation/web/news-front.itexi}
+@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):
-@item Check that lilypond builds from scratch in an out-of-tree
-build.
+@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
+make LILYPOND_BRANCH=release/unstable lilypond
@end example
@noindent
make LILYPOND_BRANCH=stable/2.12 lilypond
@end example
-
@item Check the regtest comparison in @file{uploads/webtest/} for
-any unintentional breakage.
-
-@item Check if the mingw build contains lilypad.exe; when you find
-that it doesn't, rebuild @code{mingw::lilypond-installer}. Repeat
-as necessary.
-
-@uref{http://code.google.com/p/lilypond/issues/detail?id=901}
+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 Post-release
+@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}
+@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_BRANCH=master LILYPOND_REPO_URL=git://git.sv.gnu.org/lilypond.git
+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_BRANCH=stable/2.12 LILYPOND_REPO_URL=git://git.sv.gnu.org/lilypond.git
+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
-@item Update @file{VERSION} in lilypond git.
+@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.
@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:
+@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.
-* write release notes. note: stringent size requirements for
- various websites, so be brief.
+@itemize
+@item
+Check reg test
-* write preface section for manual.
+@item
+Check all 2ly scripts
-* submit pots for translation : send url of tarball to
-translation@@iro.umontreal.ca, mentioning lilypond-VERSION.pot
+@item
+Check for emergencies the docs:
-* Check reg test
+@example
+grep FIXME --exclude "misc/*" --exclude "*GNUmakefile" \
+ --exclude "snippets/*" ????*/*
+@end example
-* Check all 2ly scripts.
+@item
+Check for altered regtests, and document as necessary. (update
+numbers in the following command as appropriate)
-* Run convert-ly on all files, bump parser minimum version.
+@example
+git diff -u -r release/2.12.0-1 -r release/2.13.13-1 input/regression/
+@end example
-* 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
+@end itemize
-* Make FTP directories on lilypond.org
-* website:
- - Make new table in download.html
+@subheading Housekeeping requirements
- - add to documentation list
+Before the release:
- - revise examples tour.html/howto.html
+@itemize
+@item
+write release notes. note: stringent size requirements for
+various websites, so be brief.
- - add to front-page quick links
+@item
+Run convert-ly on all files, bump parser minimum version.
- - change all links to the stable documentation
+@item
+Update lilypond.pot:
- - doc auto redirects to v2.LATEST-STABLE
+@example
+make -C $LILYPOND_BUILD_DIR po-replace
+mv $LILYPOND_BUILD_DIR/po/lilypond.pot po/
+@end example
- - add these two lines to http://www.lilypond.org/robots.txt:
+@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:
- comp.music.research
- comp.os.linux.announce
+@example
+comp.music.research
+comp.os.linux.announce
- comp.text.tex
- rec.music.compose
+comp.text.tex
+rec.music.compose
+@end example
Mail:
- info-lilypond@@gnu.org
+@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
+tex-music@@icking-music-archive.org
- --- non-existant?
- abcusers@@blackmill.net
+--- non-existant?
+abcusers@@blackmill.net
- rosegarden-user@@lists.sourceforge.net
- info-gnu@@gnu.org
- noteedit-user@@berlios.de
+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
+gmane.comp.audio.fomus.devel
+gmane.linux.audio.users
+gmane.linux.audio.announce
+gmane.comp.audio.rosegarden.devel
+@end example
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
+@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
-If releasing stable/2.12, then:
+@subsubheading Regenerating regression tests
+
+Regenerating regtests (if the lilypond-book naming has changed):
+
+@itemize
-- apply doc patch: patches/rsync-lily.patch (or something like
- that)
+@item
+git checkout release/lilypond-X.Y.Z-A
-- change infodir in gub/specs/lilypond-doc.py from "lilypond.info"
- to "lilypond-web.info"
+@item
+take lilypond-book and any related makefile updates from the
+latest git.
+@item
+configure; make; make test
-GENERAL STUFF TO BE MOVED ELSEWHERE
+@item
+tar -cjf lilypond-X.Y.Z-A.test-output.tar.bz2 input/regression/out-test/
-Regenerating regtests (if the lilypond-book naming has changed):
+@item
+mv lilypond-X.Y.Z-A.test-output.tar.bz2 ../gub/regtests/
-- git checkout release/lilypond-X.Y.Z-A
+@item
+cd ../gub/regtests/
-- take lilypond-book and any related makefile updates from the
- latest git.
+@item
+make lilypond
-- configure; make; make test
+@end itemize
-- tar -cjf lilypond-X.Y.Z-A.test-output.tar.bz2
- input/regression/out-test/
-- mv lilypond-X.Y.Z-A.test-output.tar.bz2 ../gub/regtests/
+@subsubheading stable/2.12
-- cd ../gub/regtests/
+If releasing stable/2.12, then:
-- make lilypond
+@itemize
+@item
+apply doc patch: patches/rsync-lily.patch (or something like
+that)
-New contributor / mentor idea:
+@item
+change infodir in gub/specs/lilypond-doc.py from "lilypond.info"
+to "lilypond-web.info"
+@end itemize
-- tell them to spend 10 minutes on a problem, then give up and ask
- for help from their mentor
+@subsubheading Updating a release (changing a in x.y.z-a)
-- the mentor should tell them if a "make clean; make" (or the same
- for docs) is required
+Really tentative instructions, almost certainly can be done
+better.
+@enumerate
-Latest website:
+@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)
-- generated hourly on lilypond.org. Only split-HTML; big-html and
- pdf are not generated hourly (wait for the next devel 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.
-VERSION-SPECIFIC MACROS
+@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
-- made with scripts/build/create-version-itexi.py
+or
-- used extensively in the WEBSITE_ONLY_BUILD version of the
- website (made with website.make, and used on lilypond.org)
+build everything with the normal "make lilypond", then (maybe)
+manually delete stuff you don't want to upload.
-- not (?) used in the main docs?
+@item
+manually upload them. good luck figuring out the rsync
+command(s). Hints are in test-lily/
-- FIXME: the numbers in VERSION: MINOR should be 1 more than the
- last release, VERSION_DEVEL should be the last *online* release.
+or
+run the normal lilypond-upload command, and (maybe) manually
+delete stuff you didn't want to upload from the server.
-LANGUAGE LISTS
+@end enumerate
-- a translator can ask for an official lilypond-xy mailing list
- once they've finished all "priority 1" translation items.
projects / lilypond.git / blobdiff