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