Steps to a Successful Release
-----------------------------
The following is a step-by-step guide for how to proceed 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 and announce in #crawl-dev.

   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.

   To give all devs a chance to speak up about outstanding pre-release issues,
   send an email to CRD giving a time-frame for the branch creation, ideally
   1-2 weeks before the branch is created.


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

   Tag message formatting:
   0.16-a0: You open the 0.16 season. It cackles and vanishes in a puff of smoke!
       -- should include the phrase "open the 0.x season"
   0.15-b1: You feel a great weight lift as you enter the 0.15 branch.
       -- should include the phrases "0.x" and "branch"
   0.15.0: 0.15 "Storm Over Zot"
       -- should be the version number followed by the tagline in quotes.


3. Update servers

   Contact the server admins to ask them to add the new version, and
   preferably to make it the default until the end of the tournament.
   This will increase the amount of playtesting the branch gets before
   release.


4. 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 game-breakers),
   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


5. 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 pre-chosen 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)


6. Update documentation files

   Update the release date in the changelog. This is a good time to make a
   final check of the Crawl manual to make sure it's updated for any relevant
   changes.

   It's ideal if you can also update the Debian changelog file before tagging
   the release, but this can be done later by the person preparing the debian
   packages. In the debian.txt guide in this directory, see the step "0.2
   Release Prerequisites" to update `source/debian/changelog` for the new
   version.


7. Tag and create the release

   In the branch you're about to tag:

   git tag -a 0.X.y
   git push --tags

   Then, visit the GitHub releases page:

   https://github.com/crawl/crawl/releases

   You should have the ability to create a release from this tag. Once you
   create the release, GitHub Actions will automatically upload macOS and
   Windows builds as release assets.


8. Package the source tarball, and produce Debian packages

   "make package-source" will create three source tar/zipballs. You can add
   these to the GitHub release as additional assets.

   For building the Debian packages and installing them into the CDO
   repository, see the debian.txt guide in this directory.


9. Update download links on CDO

    Use the crawl login on CDO to update the links on the download page
    currently at ~/website/download.htm.

    Presently there's a repository that manages the web files for non-wordpress
    pages on CDO like the splash and download pages. This repo is cloned to
    ~/dcss-website, and the origin repo on github is maintained by chequers,
    who can grant push access to new users. It's best to update the files in
    the dcss-website/site in the repo, make a commit for the change, and then
    copy the download.htm file to the live ~/website directory.

    Ideally you'll also push the commit to chequers' origin repo. In the future
    we'll probably move the website repo to the github crawl group and better
    integrate it to the CDO website directory to avoid manual copying.

    Building and installing the Debian packages is covered in the debian.txt
    guide in this directory.


10. Update Sourceforge

    We currently use Sourceforge only for the CRD mailing list. Until CRD is
    moved somewhere else, we want to keep the Sourceforge release binaries
    updated so that no (possibly broken or malware-infested) release packages
    get automatically created there. To upload to Sourceforge, you need
    permissions for file releases and then to upload through the web
    interface. It's pretty flaky and tends to break, often failing with
    specific browsers. Mark it as the default download (.tar.xz source for
    most, .exe installer for Windows).


11. Announce the release

    Post a release announcement to the CDO blog and 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. ;)