Skip to content

Release checklist

Jump to bottom Edit New page
Myk edited this page Aug 3, 2023 · 103 revisions

Beta release

This process pushes a pre-release build to the Steam beta tester pool. It is intended to be low-toil and higher frequency than the stable release process and allows us to facilitate frequent public testing and feedback without compromising the stability of our "stable" releases. These releases will not be available on the GitHub release page, but can still be downloaded from the appropriate GitHub build action.

  1. Run the Update submodules GitHub action on the develop branch to ensure that all submodules are up to date.
  2. Update version strings in CMakeLists.txt as appropriate. Set DFHACK_RELEASE to the next stable release version with an "rc#" suffix. For example, if the last stable release was "r1" then set the string to "r2rc1". If we do a second beta release before the final stable "r2" then the string would be "r2rc2".
    • Ensure the DFHACK_PRERELEASE flag is set to TRUE.
    • Commit and push to develop
  3. Tag develop (no need to tag the submodules) and push: git tag -a $RELEASE -m "Bump to $RELEASE"; git push --tags origin
  4. Run the Deploy to Steam GitHub action with the latest commit hash (or the default develop ref if it's the latest commit on develop), the full version string (e.g. "50.07-r2rc2"), and the "staging" release channel.
  5. Associate release notes with the build on Steam
    • Go to the announcement creation page
    • Select "A game update"
    • Select "Small update / Patch notes"
    • Set the "Event title" to the release version (e.g. "DFHack 50.07-r2rc2")
    • Set the "Subtitle" to "DFHack pre-release (beta channel)"
    • Mention release highlights in the "Summary" field
    • Add patch notes and any specific requests for feedback to the "Event description" field
      • patch notes must be in BBcode; see below for how to convert our release notes to BBcode
      • Run python docs/gen_changelog.py -a in your local dfhack clone and copy the text from docs/changelogs/future-github.txt
    • Click "Link to build" and select the staging branch (be sure the build has been deployed to the branch first. by the time you're done with the patch notes the build will likely be ready for you)
    • Switch to the "Publish" tab and publish!
      • Note you have to "Skip warnings" for not having sufficient artwork
    • Promote the build to the "beta" branch
  6. Monitor for beta channel subscriber feedback on the Steam community page
  7. Maybe also post to Reddit and other announcement channels if we feel like we need to recruit more beta testers into the pool, but we should avoid posting so often that it is annoying for those who don't use Steam or just want announcements for stable releases.

Stable release

This process creates a stable DFHack release meant for widespread distribution. Stable releases come in two forms: straight from develop or from a point release branch.

During "normal" times, we will test out new features in beta releases until we reach a point of stability. Then, after the develop branch is feature frozen while we polish and fix bugs, we tag a release directly from develop HEAD.

However, if we have already started committing beta features to develop and it becomes necessary to put out a bugfix release for a problem in an already-released stable release, then we will create a new branch from the stable tag, cherry-pick fixes from develop onto that branch, and spin a release from there. After the point release is published, we'll update the changelog in develop to reflect the existence of the point release, moving bugfix line items to a new section dedicated to that point release.

  1. Triage remaining issues/PRs in the release project
    • Don't feel pressure to merge anything risky just before a release. That's what beta releases are for.
  2. In your local clone of the DFHack/develop branch, make sure your checkout and all submodules (listed in .gitmodules) are up to date with their latest public commits and have no uncommitted/unpushed local changes.
  3. Ensure that CI has not failed unexpectedly on the latest online changes:
  4. Update version strings in CMakeLists.txt as appropriate. Set RELEASE in your environment for the commands below (e.g. RELEASE=50.07-r1)
  5. Ensure the DFHACK_PRERELEASE flag is set to FALSE.
  6. Replace "Future" with the version number and clean up changelog entries:
    • docs/changelog.txt
    • scripts/changelog.txt
    • library/xml/changelog.txt
  7. Add new "Future" section to all changelog.txt files
    • Pre-populate with category headers (e.g. "Fixes", "Misc Improvements", etc.). This helps contributors put entries in the correct sections.
  8. Commit changes to submodules
  9. Make sure everything compiles locally, including docs. Ensure BUILD_TESTS is ON.
    • On the title screen, run test (no arguments means all tests in all modes, including fortress mode, so have a fort save ready (in region1 by default))
  10. Tag and push submodules (e.g. git tag -a $RELEASE -m "Bump to $RELEASE"; git push --tags origin master)
    • scripts
    • library/xml
    • plugins/stonesense
  11. Commit and push changes to develop
    • Ensure that any updates you pushed to submodules are tracked in the latest commit to DFHack/develop
  12. Tag and push dfhack: git tag -a $RELEASE -m "Bump to $RELEASE"; git push --tags origin develop (replace "origin" with the DFHack repo remote if different for your setup)
    • This will re-trigger GitHub build actions for the commit, producing a build artifact that knows that it comes from a tagged commit (so devel/check-release will pass on this build).
  13. Run the Deploy to Steam GitHub action With the tagged commit hash (or the default develop ref if it's the latest commit on develop), the full version string (e.g. "50.07-r2"), and the "staging" release channel.
  14. Switch to the Steam staging release channel (password: stagingstagingstaging) and download and test the update.
    • Ensure DFHack starts DF when run from the Steam client
    • Ensure the DFHack version string is accurate on the title page (should just be the release number, e.g. DFHack 50.08-r2, with no extra information or warnings)
    • Run devel/check-release
  15. Download and test the GitHub release artifact
    • Download the build artifact from the MSVC build action for the tagged commit (e.g. not develop): image
    • Rename it to dfhack-$RELEASE-Windows-64bit.zip
    • Install to a local clean DF folder
    • Ensure version on title screen matches Steam version
    • Test world generation, embark, saving, loading, saving
    • Make sure DF quits from the main menu normally
    • Run devel/check-release
    • If something goes wrong with this or the preceding step, fix it, delete the tag both from GitHub and locally (git tag -d $RELEASE), re-tag, re-push, and re-test.
  16. Push develop to master (git push origin develop:master)
    • This will start the documentation build process and update the published "stable" docs
  17. Prep release on GitHub
    • Go to the GitHub Releases page
    • Click "Draft a new release"
    • Choose the tag you just pushed
    • Give the release a title that matches the version (e.g. "DFHack 50.07-r1")
    • Add announcements, highlights (with demo videos), etc. to the description (copy the formatting from earlier releases)
    • Run python docs/gen_changelog.py -a in your local dfhack clone, copy the text from docs/changelogs/$RELEASE-github.txt, and paste it in to the bottom of the release description
    • Upload the renamed build artifact you downloaded to attach it to the release
    • Save as draft (you'll need the preview for the next step)
  18. Post release notes on Steam
    • Go to the announcement creation page
    • Select "A game update"
    • Select "Regular update"
    • Set the "Event title" to the release version (e.g. "DFHack 50.07-r1")
    • Set the "Subtitle" to "DFHack stable release"
    • Add list of highlights to the "Summary" field
    • Add demo videos to the "Previously uploaded videos" area. You can drag the uploaded videos into place later in the event description.
    • Add release notes to the "Event description" field (must be in BBcode; see below for how to convert our release notes to BBcode)
      • If there isn't enough room for the generated release notes, add a link to the GitHub release page at the bottom of the announcement instead
    • Click "Link to build" and select the staging branch (be sure the build has been deployed to the branch first. by the time you're done with the patch notes the build will likely be ready for you)
      • the release notes will travel with the build when we promote it to the default branch
    • Go to the Artwork tab, select "Previously uploaded images", and double-click on STABLEannouncement6.png. Click Upload.
    • Switch to the "Publish" tab and publish!
  19. Go to the Steam builds page and promote the build to the "default" branch
    • For the build that you just pushed to "staging", click the "-- Select an app branch --" drop-down and select "default"
    • Click on "Preview Change"
    • Commit the change
    • If the release is newer than what's on the beta branch, set it live on the beta branch as well
  20. Publish the prepped GitHub release
  21. Send out release announcements
    • Announce new version in r/dwarffortress (example)
    • Announce new version in forum thread (example)
      • Update latest version text and link in first post (if you are not Lethosor, ping Lethosor for this)
    • Announce in #announcements on DFHack Discord
    • Announce in #mod-releases on Kitfox Discord
      • Change the name of the release thread on Kitfox Discord to match the release version (if you are not Myk, ping Myk for this)
  22. Monitor all announcement channels for feedback and respond to questions/complaints
  23. Create a project on GitHub in the DFHack org for the next release
    • Copy the previous project (3 dot menu, "Copy project"), set DFHack as the owner
    • In the new project, select settings and set the visibility to Public
    • Move any remaining To Do or In Progress items from last release project to next release project
    • Close project for last release
  24. If this is a -r2 release or later, go to https://readthedocs.org/projects/dfhack/versions/ and "Edit" previous DFHack releases for the same DF version and mark them "Hidden" (also keep them "Active") so they no longer appear on the docs version selector.

Converting Markdown to BBcode

Hopefully we can automate this in the future, but for now, here is the procedure:

  1. Get the markdown that you want to convert into some field on GitHub (can be a temporary text field that you then preview without saving)
  2. View the rendered release notes in your browser (these instructions are for Chrome, but other browsers probably have similar capabilities)
  3. Right click on the rendered text and inspect the DOM
  4. Copy the HTML element that contains the release notes
  5. Click on the "Import HTML" button on the Steam announcement form; paste in the HTML and click "Overwrite"
  6. Copy the generated BBCode out from the description field and into a text editor
  7. Fix it up:
    • h3 elements (if any) aren't converted properly and need to be rewritten with square brackets
    • Any monospaced text gets HTML tags instead of BBCode [code] tags, but you can't use them either since they force newlines. [tt] isn't supported. Any <code> tags just need to be removed entirely.
    • Any <details> and <summary> tags need to be removed
  8. Copy it all back into the description field for the announcement
  9. You're done.
Add a custom footer
Add a custom sidebar
Clone this wiki locally