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