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 2.

0.  Delay branching as long as possible
    Try to delay additions that forseeably won't make it into the next version
    until the release is not too far off. Once master has been branched, you
    have to commit all important changes twice, and it's easy to forget one
    of them.

    At the same time if something big does get introduced it's better to branch
    before doing so seeing how otherwise you'll have to later turn it off in
    branch before the release.
    Thus, you'll need to branch as early as necessary and as late as possible.

1.  Branch master into the new version
    git push origin origin:refs/heads/stone_soup.0.X

2.  Modify branch as needed
    Turn off all features that are not balanced or finished enough to make it
    into the release. This can be a bit of a hassle, so do try to avoid this in
    the first place. (See 0.)
    Also make sure that the version is correctly set to 0.X.y.

3.  Wait and fix some bugs
    Wait at least a week for some last minute bug reports. When fixing bugs
    concentrate on the important ones (crashes and gamebreakers), but you
    might also want to handle the trivial ones for extra polishing.
    If you add any last minute feature or bug fixes doublecheck everything,
    so you don't accidentally introduce new bugs, and wait at least another
    day for potential bug reports to roll in.

    Reread the entire documentation to make sure it's up to date. Update the
    PDF versions as well. Also update the change log!

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 (including loading from previous minor version)
        * being killed
        * level creation for all branches/portal vaults (using &~, &L)
        * accessing all help screens (including the ? submenus)

    If you want to be thorough, play a tutorial for each of the three character
    builds. This way, you get to test melee, spellcasting, and ranged combat,
    and at the same time you can check that the information handed out during
    the tutorial is up to date.

5.  Package the source tarball and zip
    On Linux, run "make package-source" in the source tree to create the source
    tarball and zip. Extract the resulting packages into different folders,
    compile their source and run the basic sanity tests. Also check whether
    the doc, settings and dat subfolders contain all relevant files.

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

    You'll need to push the tag into repository:
    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 either make it into the next (minor) version, or, if they are
    important bug fixes and happen before the release took place, have to be
    merged into trunk AND branch AND the corresponding tag.

    Tagging a branch with 0.X with alpha or beta qualifier will automatically
    take care of updating the version type to FINAL and thus suppress the
    revision output in the version information.

7.  Checkout the release tag
    git checkout -b stone_soup-0.X release-0.X.y

    You may want to make a new shallow clone into a new folder, to make sure
    you don't get any compilation stuff into the distribution.

    Package the source (as described in 6.) and build the binaries. If you want
    you can do some more sanity testing but it shouldn't be necessary anymore.

8.  Upload the files to Sourceforge
    Probably requires SF permissions for file releases.

    You could use for example rsync (on Linux) or FTP.
    See https://sourceforge.net/apps/trac/sourceforge/wiki/File%20management%20service
    for reference. Compare the file sizes to make sure the upload went
    correctly.

    If using rsync, the correct command is:
    rsync -avP -e ssh FILENAME USERNAME,crawl-ref@frs.sourceforge.net:/home/frs/project/c/cr/crawl-ref/

9.  Create a new release in Sourceforge's file release system
    Requires SF permissions for file releases.

    * Click on Project Admin -> File Manager
    * Create a new folder under "Stone Soup" named by version number -> 0.X.y
    * Right-click on the uploaded files to Cut and later Paste them into the
      newly created folder.
    * Click on a file to change its settings.
    * Mark a file as default for a given platform, so the "Download Now" link
      can refer the user to the most fitting file for their system.

    You can use an older release as a guideline (but don't actually modify it!)
    See https://sourceforge.net/apps/trac/sourceforge/wiki/Release%20files%20for%20download
    for some more detailed explanations.

    Also, paste the changelog into a newly created 0.X.txt, and upload it
    into the folder as well.

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. ;)
