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