Documentation/contributor/release-work.itexi

   1 @c -*- coding: utf-8; mode: texinfo; -*-
   2 @node Release work
   3 @chapter Release work
   4
   5 @menu
   6 * Development phases::
   7 * Minor release checklist::
   8 * Major release checklist::
   9 * Release extra notes::
  10 @end menu
  11
  12
  13 @node Development phases
  14 @section Development phases
  15
  16 There are 2.5 states of development for LilyPond.
  17
  18 @itemize
  19
  20 @item @strong{Stable phase}:
  21 Starting from the release of a new major version @code{2.x.0}, the
  22 following patches @strong{MAY NOT} be merged with master:
  23
  24 @itemize
  25 @item Any change to the input syntax.  If a file compiled with a
  26 previous @code{2.x} version, then it must compile in the new
  27 version.
  28
  29 @item New features with new syntax @emph{may be committed},
  30 although once committed that syntax cannot change during the
  31 remainder of the stable phase.
  32
  33 @item Any change to the build dependencies (including programming
  34 libraries, documentation process programs, or python modules used
  35 in the buildscripts).  If a contributor could compile a previous
  36 lilypond @code{2.x}, then he must be able to compile the new
  37 version.
  38
  39 @end itemize
  40
  41 @item @strong{Development phase}:
  42 Any commits are fine.  Readers may be familiar with the term
  43 @qq{merge window} from following Linux kernel news.
  44
  45
  46 @item @strong{Release prep phase}:
  47 TODO: I don't like that name.
  48
  49 A new git branch @code{stable/2.x} is created, and a major release
  50 is made in two weeks.
  51
  52 @itemize
  53
  54 @item @code{stable/2.x branch}:
  55 Only translation updates and important bugfixes are allows.
  56
  57 @item @code{master}:
  58 Normal @qq{stable phase} development occurs.
  59
  60 @end itemize
  61
  62 If we discover the need to change the syntax or build system, we
  63 will apply it and re-start the release prep phase.
  64
  65 @end itemize
  66
  67 This marks a radical change from previous practice in LilyPond.
  68 However, this setup is not intended to slow development -- as a
  69 rule of thumb, the next development phase will start within a
  70 month of somebody wanting to commit something which is not
  71 permitted during the stable phase.
  72
  73
  74
  75 @node Minor release checklist
  76 @section Minor release checklist
  77
  78 A @qq{minor release} means an update of @code{y} in @code{2.x.y}.
  79
  80 @subheading Pre-release
  81
  82 @enumerate
  83
  84 @item
  85 Switch to the release branch, get changes, prep release
  86 announcement:
  87
  88 @example
  89 git checkout release/unstable
  90 git merge origin
  91 vi Documentation/web/news-front.itexi Documentation/web/news.itexi
  92 @end example
  93
  94 @item
  95 Commit, push, switch back to master:
  96
  97 @example
  98 git commit -m "Release: update news." Documentation/web/
  99 git push origin
 100 @end example
 101
 102 @item (optional) Check that lilypond builds from scratch in an
 103 out-of-tree build.
 104
 105 @item
 106 If you do not have the previous release test-output tarball, download
 107 it and put it in @code{regtests/}
 108
 109 @item Build release on GUB by running:
 110
 111 @example
 112 make LILYPOND_BRANCH=release/unstable lilypond
 113 @end example
 114
 115 @noindent
 116 or something like:
 117
 118 @example
 119 make LILYPOND_BRANCH=stable/2.12 lilypond
 120 @end example
 121
 122 @item Check the regtest comparison in @file{uploads/@/webtest/} for
 123 any unintentional breakage.  More info in
 124 @ref{Precompiled regression tests}
 125
 126 @item If any work was done on GUB since the last release, upload
 127 binaries to a temporary location, ask for feedback, and wait a day
 128 or two in case there's any major problems.  Or live dangerously
 129 and just add a sentence to the release notes.  Or live even more
 130 dangerously, and don't tell anybody anything.
 131
 132 @end enumerate
 133
 134
 135 @subheading Actual release
 136
 137 @enumerate
 138
 139 @item If you're not right user on the webserver, remove the "t"
 140 from the rsync command in @file{test@/-lily/@/rsync@/-lily@/-doc@/.py} and
 141 @file{test@/-lily/@/rsync@/-test@/.py}
 142
 143 @code{graham} owns v2.13; @code{han-wen} owns v2.12.
 144
 145 @item Upload GUB by running:
 146
 147 @example
 148 make lilypond-upload LILYPOND_BRANCH=release/unstable LILYPOND_REPO_URL=git://git.sv.gnu.org/lilypond.git
 149 @end example
 150
 151 @noindent
 152 or something like:
 153
 154 @example
 155 make lilypond-upload LILYPOND_BRANCH=stable/2.12 LILYPOND_REPO_URL=git://git.sv.gnu.org/lilypond.git
 156 @end example
 157
 158 @end enumerate
 159
 160
 161 @subheading Post release
 162
 163 @enumerate
 164
 165 @item Switch back to master and get the updated news:
 166
 167 @example
 168 git checkout master
 169 git merge release/unstable
 170 @end example
 171
 172 @item Update @file{VERSION} in lilypond git and upload changes:
 173
 174 @example
 175 vi VERSION
 176 @end example
 177
 178 @itemize
 179 @item
 180 VERSION = what you just did +0.0.1
 181
 182 @item
 183 DEVEL_VERSION = what you just did (i.e. is now online)
 184
 185 @item
 186 STABLE_VERSION = what's online (probably no change here)
 187
 188 @end itemize
 189
 190 @example
 191 git commit -m "Release: bump version." VERSION
 192 git push origin
 193 @end example
 194
 195
 196 @item (for now) do a @code{make doc} and manually upload:
 197
 198 @example
 199 ### upload-lily-web-media.sh
 200 #!/bin/sh
 201 BUILD_DIR=$HOME/src/build-lilypond
 202
 203 PICS=$BUILD_DIR/Documentation/pictures/out-www/
 204 EXAMPLES=$BUILD_DIR/Documentation/web/ly-examples/out-www/
 205
 206 cd $BUILD_DIR
 207 rsync -a $PICS graham@@lilypond.org:media/pictures
 208 rsync -a $EXAMPLES graham@@lilypond.org:media/ly-examples
 209 @end example
 210
 211 @item Wait a few hours for the website to update.
 212
 213 @item Email release notice to @code{info-lilypond}
 214
 215 @end enumerate
 216
 217
 218
 219 @node Major release checklist
 220 @section Major release checklist
 221
 222 A @qq{major release} means an update of @code{x} in @code{2.x.0}.
 223
 224 - happens when we have 0 Critical issues for two weeks (14 days).
 225
 226
 227 Before release:
 228
 229 * write release notes. note: stringent size requirements for
 230  various websites, so be brief.
 231
 232 * write preface section for manual.
 233
 234 * submit pots for translation: send url of tarball to
 235 translation@@iro.umontreal.ca, mentioning lilypond-VERSION.pot
 236
 237 * Check reg test
 238
 239 * Check all 2ly scripts.
 240
 241 * Run convert-ly on all files, bump parser minimum version.
 242
 243 * update links to distros providing lilypond packages?  link in
 244 Documentation/web/download.itexi .  This has nothing to do with
 245 the release, but I'm dumping this here so I'll find it when I
 246 reorganize this list later.  -gp
 247
 248 * Make FTP directories on lilypond.org
 249
 250 * website:
 251   - Make new table in download.html
 252
 253   - add to documentation list
 254
 255   - revise examples tour.html/howto.html
 256
 257   - add to front-page quick links
 258
 259   - change all links to the stable documentation
 260
 261   - make a link from the old unstable to the next stable in
 262     lilypond.org's /doc/ dir.  Keep all previous unstable->stable
 263     doc symlinks.
 264
 265   - doc auto redirects  to v2.LATEST-STABLE
 266
 267   - add these two lines to http://www.lilypond.org/robots.txt:
 268
 269 @example
 270 Disallow: /doc/v2.PREVIOUS-STABLE/
 271 Disallow: /doc/v2.CURRENT-DEVELOPMENT/
 272 @end example
 273
 274 - check for emergencies the docs:
 275
 276 @example
 277 grep FIXME --exclude "misc/*" --exclude "*GNUmakefile" \
 278   --exclude "snippets/*" ????*/*
 279 @end example
 280
 281 - check for altered regtests, and document as necessary.  (update
 282   tags as appropriate)
 283
 284 @example
 285 git diff -u -r release/2.12.0-1 -r release/2.13.13-1 input/regression/
 286 @end example
 287
 288
 289 News:
 290
 291         comp.music.research
 292         comp.os.linux.announce
 293
 294         comp.text.tex
 295         rec.music.compose
 296
 297 Mail:
 298
 299         info-lilypond@@gnu.org
 300
 301 linux-audio-announce@@lists.linuxaudio.org
 302 linux-audio-user@@lists.linuxaudio.org
 303 linux-audio-dev@@lists.linuxaudio.org
 304
 305         tex-music@@icking-music-archive.org
 306
 307    --- non-existant?
 308         abcusers@@blackmill.net
 309
 310         rosegarden-user@@lists.sourceforge.net
 311         info-gnu@@gnu.org
 312         noteedit-user@@berlios.de
 313
 314         gmane.comp.audio.fomus.devel
 315         gmane.linux.audio.users
 316         gmane.linux.audio.announce
 317         gmane.comp.audio.rosegarden.devel
 318
 319 Web:
 320
 321         lilypond.org
 322         freshmeat.net
 323         linuxfr.com
 324         http://www.apple.com/downloads
 325         harmony-central.com (news@@harmony-central.com)
 326         versiontracker.com [auto]
 327         hitsquad.com [auto]
 328         http://www.svgx.org
 329         https://savannah.gnu.org/news/submit.php?group_id=1673  @c => planet.gnu.org
 330
 331
 332 @node Release extra notes
 333 @section Release extra notes
 334
 335 @subsubheading Regenerating regression tests
 336
 337 Regenerating regtests (if the lilypond-book naming has changed):
 338
 339 @itemize
 340
 341 @item
 342 git checkout release/lilypond-X.Y.Z-A
 343
 344 @item
 345 take lilypond-book and any related makefile updates from the
 346 latest git.
 347
 348 @item
 349 - configure; make; make test
 350
 351 @item
 352 tar -cjf lilypond-X.Y.Z-A.test-output.tar.bz2 input/regression/out-test/
 353
 354 @item
 355 mv lilypond-X.Y.Z-A.test-output.tar.bz2 ../gub/regtests/
 356
 357 @item
 358 cd ../gub/regtests/
 359
 360 @item
 361 make lilypond
 362
 363 @end itemize
 364
 365
 366 @subsubheading stable/2.12
 367
 368 If releasing stable/2.12, then:
 369
 370 @itemize
 371
 372 @item
 373 apply doc patch: patches/rsync-lily.patch  (or something like
 374 that)
 375
 376 @item
 377 change infodir in gub/specs/lilypond-doc.py from "lilypond.info"
 378 to "lilypond-web.info"
 379 @end itemize
 380
 381 @subsubheading Updating a release (changing a in x.y.z-a)
 382
 383 Really tentative instructions, almost certainly can be done
 384 better.
 385
 386 @enumerate
 387
 388 @item
 389 change the VERSION back to release you want.  push change.
 390 (hopefully you'll have forgotten to update it when you made your
 391 last release)
 392
 393 @item
 394 make sure that there aren't any lilypond files floating around in
 395 target/  (like usr/bin/lilypond).
 396
 397 @item
 398 build the specific package(s) you want, i.e.
 399
 400 @example
 401 bin/gub mingw::lilypond-installer
 402 make LILYPOND_BRANCH=stable/2.12 -f lilypond.make doc
 403 bin/gub --platform=darwin-x86 'git://git.sv.gnu.org/lilypond-doc.git?branch=stable/2.12'
 404 @end example
 405
 406 or
 407
 408 build everything with the normal "make lilypond", then (maybe)
 409 manually delete stuff you don't want to upload.
 410
 411 @item
 412 manually upload them.  good luck figuring out the rsync
 413 command(s).  Hints are in test-lily/
 414
 415 or
 416
 417 run the normal lilypond-upload command, and (maybe) manually
 418 delete stuff you didn't want to upload from the server.
 419
 420 @end enumerate
 421
 422
 423