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