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