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