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