Steps to a Successful Release
-----------------------------
The following is a step-by-step guide for how to preceed through the releasing
process. For minor releases (0.X.y), steps 0 and 1 have already been done, so
for those the list begins with step 3.

0.  Delay branching until all features are there
    It makes little sense to cherry-pick actual features, or even a major
    amount of bug fixes.  If there are features not meant for the release,
    please put them on a new branch.  In git, branching and merging is
    cheap.

1.  Branch master into the new version
    git branch stone_soup.0.X
    git push origin stone_soup.0.X

2.  Tag the branch point
    git tag -s 0.X-b1
    git push origin 0.X-b1
    Also, after the next diverging commit, tag the trunk as 0.${X+1}-a0; you
    need to make sure the commits pointed to by 0.X-b1 and 0.${X+1}-a0 are
    different.

3.  Wait and fix some bugs
    Wait at least 2-3 weeks for bug reports, and fix all severe old ones.
    When fixing bugs concentrate on the important ones (crashes and
    gamebreakers), but you might also want to handle the trivial ones for
    extra polishing.  Do not EVER add any last minute features unless they
    can't possibly introduce new bugs.

    Reread the entire documentation to make sure it's up to date.  Also
    update the change log!

    To check for candidates for cherry-picking:
    (on master) git cherry -v origin/stone_soup.0.X
    To actually take them:
    (on stone_soup.0.X) git cherry-pick -x 0123456789abc

4.  Sanity testing
    Build the binaries (preferably on all platforms) to see if the code
    compiles correctly, then run some basic sanity tests including at least
    the following:
        * start a new game (both prechosen and random)
        * saving/loading
          * if there were changes that can affect saves, load a save from a
            previous minor version
        * being killed
        * level creation for all branches/portal vaults (using &~, &L)
        * accessing all help screens (including the ? submenus)

5.  Sync the documentation
    Update the release date in the changelog.
    In major releases (not point ones!), use "make rest" to fetch the the
    manual from the wiki
    (https://crawl.develz.org/wiki/doku.php?id=dcss:manual:rest).  Remember
    that after the release the wiki refers to the next major version, so any
    further changes need to be done in the git tree directly.  Commit.

6.  Tag the release
    In the branch you're about to tag:
    git tag -s 0.X.y

    Don't push the tag yet so you can make final amendments.

7.  Package the source tarball, produce final builds

    "make package-source" will create three source tar/zipballs.

    For binary builds, you need to ensure at least the dat/ subdir contains
    no foreign files (such as editor backup files, uncommitted stuff, random
    junk, etc).  Thus, "git clean -dfx".  This is a potentially destructive
    operation so if you have files lying around, you may want to do this
    from a separate clone instead.

    Release is when you may go wild with optimizations -- the binaries will
    be compiled once, used by thousands of users!  Currently, the
    recommended settings are LTO and -O2 (with C++'s code size bloat, -O3 is
    actually slower), although this is likely to change in the future.  If
    you want to bother with profile-guided stuff, this is the time.

    The makefile targets are "package-windows" and "package-windows-zips"
    for the installer and stand-alone zips respectively.  Unless you're on
    msys, you need to specify CROSSHOST as well:
    make LTO=y CROSSHOST=i686-w64-mingw32 package-windows

    Some final testing never hurts; we're supposed to support win2k so test
    there as well.

8.  Push the tag
    Until the moment you push it to the official repository, you can delete
    it and re-tag.
    git push --tags

    The tags are some sort of frozen state of the source for all releases,
    so this is the last step you take before the actual release.  All
    further changes make it into the next minor version.

9.  Upload the files to Sourceforge
    Requires SF permissions for file releases.

    FTP/rsync access is no more, you need to use the web interface.  It is
    pretty flaky and tends to break, often failing with specific browsers.

    Finally, mark it as the default download (.tar.xz source for most, .exe
    installer for Windows).

10. Update the homepage
    Modify the Downloads page over at
    http://crawl.develz.org/wordpress/downloads/ as necessary.

11. Announce the release
    Post a release announcement to the CDO blog, rec.games.roguelike.misc and
    rec.games.roguelike.announce. Also send an email over crawl-ref-discuss.
    If you want you can also write a news item on Sourceforge.

12. Lean back and enjoy the excitement
    -- until the first bug reports roll in. ;)
