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 origin
 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 @subsubheading Performing yearly copyright update (@qq{grand-replace})
 410
 411 At the start of each year, copyright notices for all source files
 412 should be refreshed by running the following command from the top of
 413 the source tree:
 414
 415 @example
 416 make grand-replace
 417 @end example
 418
 419 Internally, this invokes the script @file{scripts/build/grand-replace.py},
 420 which performs a regular expression substitution for old-year -> new-year
 421 wherever it finds a valid copyright notice.
 422
 423 Note that snapshots of third party files such as @file{texinfo.tex} should
 424 not be included in the automatic update; @file{grand-replace.py} ignores these
 425 files if they are listed in the variable @code{copied_files}.