X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;ds=sidebyside;f=Documentation%2Fcontributor%2Frelease-work.itexi;h=aa133413fe7a808df7448d2a82b9dceb6224d18b;hb=f8e03b152b436d6034dd17e71335fc6221497571;hp=dab57e4f68ff5bd6d7ae550eb70cb72e7842fcee;hpb=74b336b3cab541e5f57c11c33ff52475eb655414;p=lilypond.git diff --git a/Documentation/contributor/release-work.itexi b/Documentation/contributor/release-work.itexi index dab57e4f68..aa133413fe 100644 --- a/Documentation/contributor/release-work.itexi +++ b/Documentation/contributor/release-work.itexi @@ -1,30 +1,50 @@ -@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 @@ -38,38 +58,10 @@ 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. +@item @strong{Release prep}: +Only translation updates and important bugfixes are allowed. +@end enumerate @node Minor release checklist @@ -81,19 +73,53 @@ A @qq{minor release} means an update of @code{y} in @code{2.x.y}. @enumerate -@item Add a news item to @file{Documentation/web/news-front.itexi} +@item +Switch to the release branch, get changes, prep release +announcement: -@item Check that lilypond builds from scratch in an out-of-tree -build. +@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 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 @@ -103,48 +129,102 @@ or something like: 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 Switch back to master and get the updated news: + +@example +git checkout origin/staging +git merge 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 -@item Update @file{VERSION} in lilypond git. +@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. @@ -153,161 +233,283 @@ make lilypond-upload LILYPOND_BRANCH=stable/2.12 LILYPOND_REPO_URL=git://git.sv. @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 -* write release notes. note: stringent size requirements for - various websites, so be brief. +This is the current official guidelines. -* write preface section for manual. +@itemize +@item +0 Critical issues for two weeks (14 days) after the latest release +candidate. -* submit pots for translation : send url of tarball to -translation@@iro.umontreal.ca, mentioning lilypond-VERSION.pot +@end itemize + + +@subheading Potential requirements + +These might become official guidelines in the future. -* Check reg test +@itemize +@item +Check reg test -* Check all 2ly scripts. +@item +Check all 2ly scripts -* Run convert-ly on all files, bump parser minimum version. +@item +Check for emergencies the docs: -* 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 +@example +grep FIXME --exclude "misc/*" --exclude "*GNUmakefile" \ + --exclude "snippets/*" ????*/* +@end example -* Make FTP directories on lilypond.org +@item +Check for altered regtests, and document as necessary. (update +numbers in the following command as appropriate) -* website: - - Make new table in download.html +@example +git diff -u -r release/2.12.0-1 -r release/2.13.13-1 input/regression/ +@end example - - add to documentation list +@end itemize - - revise examples tour.html/howto.html - - add to front-page quick links +@subheading Housekeeping requirements - - change all links to the stable documentation +Before the release: - - doc auto redirects to v2.LATEST-STABLE +@itemize +@item +write release notes. note: stringent size requirements for +various websites, so be brief. - - add these two lines to http://www.lilypond.org/robots.txt: +@item +Run convert-ly on all files, bump parser minimum version. + +@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 pots for translation: send url of tarball to +translation@@iro.umontreal.ca, 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 -- apply doc patch: patches/rsync-lily.patch (or something like - that) +Regenerating regtests (if the lilypond-book naming has changed): -- change infodir in gub/specs/lilypond-doc.py from "lilypond.info" - to "lilypond-web.info" +@itemize +@item +git checkout release/lilypond-X.Y.Z-A -GENERAL STUFF TO BE MOVED ELSEWHERE +@item +take lilypond-book and any related makefile updates from the +latest git. -Regenerating regtests (if the lilypond-book naming has changed): +@item +configure; make; make test -- git checkout release/lilypond-X.Y.Z-A +@item +tar -cjf lilypond-X.Y.Z-A.test-output.tar.bz2 input/regression/out-test/ -- take lilypond-book and any related makefile updates from the - latest git. +@item +mv lilypond-X.Y.Z-A.test-output.tar.bz2 ../gub/regtests/ -- configure; make; make test +@item +cd ../gub/regtests/ -- tar -cjf lilypond-X.Y.Z-A.test-output.tar.bz2 - input/regression/out-test/ +@item +make lilypond + +@end itemize -- mv lilypond-X.Y.Z-A.test-output.tar.bz2 ../gub/regtests/ -- cd ../gub/regtests/ +@subsubheading stable/2.12 -- make lilypond +If releasing stable/2.12, then: + +@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.