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