Make sure to read the Overview first to familiarise yourself with out release process and terms we use.

Then follow the detailed instructions when it's time to carry out the release tasks:

• Plan the next release
• Create a release candidate
• Create the final release
• Create a patch release (optional)

---

Overview

We are aiming to release at least one major stable release every 12 months.

Here is a detailed description of our release process:

main branch

The main branch always contains the current development version. Assuming the current stable version is v0.80.1, the main branch corresponds to v0.81.0-alpha (the alpha version of the next release).

Release branches

When the time comes to release the next version, the release/0.81.x release branch needs to be created off main first. Every v0.81.x artifact is built from the release branch, and each published version is marked by annotated Git tags (e.g., v0.81.0-rc1, v0.81.0, v0.81.1, etc).

After creating the release branch, main holds the next alpha release, v0.82.0-alpha.

Release candidates

The release candidates (RC) aim to ensure quality and minimise the risk of bugs and regressions creeping into the next release. Early adopters are encouraged to try the RC and report issues if they run into any. This is of crucial importance as we're a small team with limited resources to perform comprehensive regression testing.

We always release at least one RC first (v0.81.0-rc1), optionally followed by more RCs if we need to gain more confidence (v0.81.0-rc2, v0.81.0-rc3, etc.)

Code freeze period

Once the first RC is out, we're in a code freeze period until the final version is released. Only regression fixes or very straightforward, surgical fixes of existing bugs are allowed to be merged to main until the final is out.

The core team's focus is testing during this period to ensure the quality of our next stable release. The idea is to prevent the need for patch releases as much as possible.

The code freeze period should ideally be between 1 and 2 months.

Patch releases

If serious regressions are found in the first few months after releasing the next stable version, we'll need to fix them in path releases. The fixes need to be backported to the release/0.81.x branch, and a new release tag needs to be created with the patch version incremented (e.g., v0.81.1, v0.81.2, etc.)

---

Detailed instructions

The below sections contain detailed step-by-step instructions for the various release actions.

Note

The 0.81.x version is just an example. Don't forget to replace 0.81.x with the actual release version as you perform these steps.

Plan the next release

When: 1-3 months before the planned release date of the RC (Release Candidate), depending on the scope

• TODO
• Keep updating the project board accordingly

Create a release candidate

Preparatory steps

When: 2-3 weeks before the planned release date of the RC

1. Set a planned date for the release candidate about 3 weeks from the current date. The purpose of this is not to put unnecessary stress on the team; it's just easier to work backwards from a concrete date for the preparatory steps. We shouldn't try too hard to hit an arbitrary date if there are complications; in that case, we will allow the release to slip.

2. Finalise the scope of the release. Only bug fixes and translations should be committed to main 1-2 weeks before the release date. You can think of it as a "soft code freeze" period.

3. Create the release notes for the release candidate. Use the output of the release drafter and follow the conventions established in the previous release notes. Give the team at least 4-5 days before the release date to review the notes and make changes if necessary.

   • The main branch always contains the website and documentation sources for the next release, so the new release notes need to go into main. Deploy the preview website off main to show the release notes to the team.

   • To compile the list of sponsors, supporters and backers, export the CSV of all transactions from OpenCollective and check the list of active GitHub sponsors for the release period.

Create the release branch

When: 2-3 days before the planned release date of the RC

1. Create a new release branch off main, e.g., release/0.81.x. You'll need to perform all further steps on this release branch.

2. Update the "Deploy website" GitHub workflow on main so it points to the new release branch release/0.81.x.

3. Add the release candidate download links to the Windows, Linux and macOS download pages. Use an earlier commit as a template and update the version in the download links. Leave the SHA256 hashes empty for now.

Tag the release candidate

When: 2-3 days before the planned release date of the RC

1. Update/add the new version in the following places. You can also check out an earlier "Bump 0.XX.X version to 0.XX.X" commit for a concrete example. Commit these changes as "Bump version to 0.81.0-RC1"

   • Update the version to 0.81.0 in these files (no "-rc1" suffix):

     • src/winres.rc (update the year too)
     • tests/files/dosbox-staging-tests.conf

   • Update the version to 0.81.0-rc1 in these files:

     • include/version.h
     • vcpkg.json
     • README
     • Add the new release to contrib/linux/dosbox-staging.metainfo.xml with today's date (the date cannot be in the future!)

   • Update the year in the "Copyright 2024 The DOSBox Staging Team" string in contrib/macos/Info.plist.template

2. Create an annotated tag for the release candidate and push up the new tag:

   git tag -a v0.81.0-rc1 -m "DOSBox Staging 0.81.0-rc1 release"
   git push origin v0.81.0-rc1
   

3. Verify the new tag exists on the Tags page.

Test internally

When: 2-3 days before the planned release date of the RC

Download the release builds under the 0.81.0-rc1 release tag and test them briefly on all platforms. Make sure the correct version string (0.81.0-rc1) shows up at startup and in the logs.

What to test specifically:

Windows

• Test both the ZIP package and the installer.
• Make sure the installer shows the correct version string.
• Make sure the installed context menus work.
• Confirm that uninstalling works.
• Ideally, perform the tests on both Windows 10 and 11.

macOS

• Make sure the image in the DMG installer looks as it should.
• Make sure to test on the lowest supported OS version (e.g., Catalina).
• Ideally, test on both Intel and ARM machines, but at least test the Intel binary on ARM Macs via Rosetta (right-click on the DOSBox Staging icon, then tick the Open using Rosetta option).

Linux

• Make sure the statically compiled binary works.

Update an existing release candidate (optional)

WARNING: You should NOT do this after the RC has been released to the public!
This is only for fixing up mistakes or adding last-minute changes BEFORE the public release!

1. Delete the release tag: Go the Tags tab of the Releases page, click on the release candidate you want to update (e.g. v0.81.0-rc1), then click on the Delete button (there will be a confirmation dialog).

2. Move the existing tag forward on your local branch with the following command (assuming you have new commits in the release branch, so you want the updated tag point to the last commit):

   git tag -fa v0.81.0-rc1
   

   Your default editor will open with the existing tag annotation; just save it and exit.

3. Push the updated tag to the repo:

   git push origin v0.81.0-rc1
   

Publish the release candidate

When: On the release date

Once the team is happy with the builds on all platforms, it's time to release the RC to the public.

1. Download the release builds under the 0.81.0-rc1 release tag.

2. Repackage the release builds:

   Windows

   • Unzip the installer version, so you're left with an .exe file.

   • Use scripts/repackage-windows-zip.sh to repackage the ZIP package, then verify the resulting ZIP file with zip -sf. The output should look like this:

     Archive contains:
       dosbox-staging-v0.81.0-rc1/
       dosbox-staging-v0.81.0-rc1/SDL2_net.dll
       dosbox-staging-v0.81.0-rc1/libvorbisenc-2.dll
       ...
       dosbox-staging-v0.81.0-rc1/resources/
       dosbox-staging-v0.81.0-rc1/resources/mapping/
       dosbox-staging-v0.81.0-rc1/resources/mapping/DECOMPOSITION.TXT
       ...
     

   macOS

   • Unzip the ZIP file generated by the CI workflow, leaving you with a .dmg file.
   • Notarising the DMG file is currently an offline process and kklobe's responsibility. Ask him to do it for you and upload the notarised DMG somewhere.

   Linux

   • Unzip the ZIP file generated by the CI workflow, leaving you with a .tar.xz file.

   At this point, you should have the following four files:

   • dosbox-staging-linux-v0.81.0-rc1.tar.xz
   • dosbox-staging-macOS-v0.81.0-rc1.dmg
   • dosbox-staging-windows-v0.81.0-rc1-setup.exe
   • dosbox-staging-windows-v0.81.0-rc1.zip

3. Run sha256sum against the final packages, and update the Windows, Linux and macOS download pages with the SHA256 checksums on the release/0.81.x branch.

4. On GitHub, create a new release from the releases area of GitHub using the existing tag, and drag the binaries onto the release (TODO clarify). You should perform the remaining few steps quickly (ideally within an hour) as the release is technically publicly available at this point.

5. Redeploy the preview website off the release/0.81.x branch, then verify that all the download links work.

6. At least double-check the SHA256 hashes of the downloaded artifacts against the hashes on the website. Ideally, also quickly smoke-test the releases one more time.

7. If all is fine, deploy the main website off the release/0.81.x branch, then announce the release. Time to open a beer or something 🥳 🍻

Post-release actions

When: In the next few days after publishing the RC

After the release candidate has been published, the main branch needs to point to the next alpha release.

Perform the steps described in the Tag the release candidate section but use the v0.82.0-alpha tag.

Additionally, update the version number in the following files:

• .github/ISSUE_TEMPLATE/bug_report.yml
• .github/ISSUE_TEMPLATE/feature_request.yml
• .github/ISSUE_TEMPLATE/question.yml

Rollback (optional)

Sometimes mistakes happen, in which case you might want to delete the newly created release and roll back the website to its previous state.

• Roll back the website: Deploy the main website off the previous (!) release branch, so release/0.80.x in this case (pay attention to the version number). This is because the main branch always contains the website's state for the next release.

1. Deploy the current and dev preview websites manually (more info in DOCUMENTATION.md):

   • Run the "Deploy website" GitHub workflow with the default parameters to deploy the current website (that includes the release notes and the updated download pages). Double-check that the "Branch to deploy the website from" contains the name of the new release branch.

   • Run the "Deploy website" GitHub workflow again to deploy the dev preview page off main (which is now identical to the release branch): use main as the source branch and enter dev for the deploy path prefix.

Create further release candidates (optional)

Further public release candidates might be necessary to gain more confidence in the bug and regression fixes made after releasing the RC. To release a new RC:

1. Backport the fixes merged to main since the RC was released into the release branch. We usually do this via cherry-picking.

2. Repeat the RC process: Perform the steps in the Creating a release candidate section, starting from the Tag the release candidate subsection.

Create the final release

1. Remove the release candidate suffix from the version:

   • Remove the "-rc1" suffix from the following files:

     • include/version.h
     • vcpkg.json
     • contrib/linux/org.dosbox-staging.dosbox-staging.metainfo.xml (update the release date too)
     • README

2. Create an annotated tag for the release on the release branch and push it up:

   git tag -a v0.81.0 -m "DOSBox Staging 0.81.0 release"
   git push origin v0.81.0
   

3. Download & repackage the final release artifacts from CI. Make sure to download the artifacts tagged as v0.81.0, then follow the repackaging and hash generation steps from the Publish release candidate section (steps 2 and 3).

4. Update the download pages for the release. Update the Windows, Linux and macOS download pages with the correct download hashes and links, and make sure the website, various guides, and the manual is fully updated for the new release. Merge these changes to main (we'll cherry-pick them to the release branch a bit later), deploy the preview website and verify that everything looks as it should.

5. Create the new release by opening the new tag on the Tags page in GitHub (it should be the topmost tag, v0.81.0 in this case). Click the Create release from tag button and drag the release packages into the "attach binaries" area. There should be four files:

   • dosbox-staging-linux-v0.81.0.tar.xz
   • dosbox-staging-macOS-v0.81.0.dmg
   • dosbox-staging-windows-v0.81.0-setup.exe
   • dosbox-staging-windows-v0.81.0.zip

   Set as pre-release should be unchecked, Set as the latest release should be checked, and leave Create a discussion for this release unchecked.

   Enter 0.81.0 Release for the title and link to the release notes in the description:

   0.81.0 release notes: https://dosbox-staging.github.io/releases/release-notes/0.81.0/
   

   Press the Publish release button.

6. Make the release branch the source for the main website: update the default source_branch value to release/0.81.x in .github/workflows/deploy-website.yml in main. Now the release/0.81.x branch is where the main website should be deployed until the next release!

7. Deploy the main website: cherry-pick the website updates from main to the release/0.81.x release branch, then run the Deploy website workflow with the default parameters. Confirm that release/0.81.x is pre-filled in the first "source branch" text field.

   Wait a few minutes until the new website becomes online (this can take up to half an hour if GitHub is under load). Confirm that the website looks as it should.

8. Forward port the Linux release metadata XML to the main branch (contrib/linux/dosbox-staging.metainfo.xml).

9. Double-check the new release packages by downloading all of them and, ideally, quickly smoke-testing them one last time.

10. Announce the release via the usual channels. Congratulations, you've made it! 🎉

Post-release actions

1. Execute the following on main to figure out the exact date of the latest release tag (replace v0.81.0 with the tag of the latest release):

   TZ=UTC git show --date='format-local:%Y-%m-%dT%H:%M:%SZ' --format="%cd" --summary tags/v0.81.0
   

2. Open .github/workflows/draft-release-notes.yml to update the release drafter to the new alpha version. Copy the ISO timestamp printed out by the command and replace the timestamp after RELEASE_START_TIME with it. Also change DRAFT_RELEASE_TAG to that of the current alpha version (e.g., 0.82.0-alpha).

3. Push the change to main, then verify the release notes draft on the releases page in a few minutes. Delete the previous release notes draft once the new one has appeared.

4. Merge any website related changes from the release branch to main. The website/ folder in the release branch and main should be in perfect sync at the start of the new release cycle for major releases (but not for patch releases; see these notes). You can verify this with the following command:

   git diff release/0.81.x..main -- website
   

5. After you've synced the website folder in main, deploy the preview website off main for good measure.

Create a patch release (optional)

Creating a patch release is very similar to creating a regular release, just you don't need to create a new branch, only a new tag.

Other notable differences:

• When merging the website-related changes back to the main branch, only merge the release notes, download pages, and the front page. The rest of the documentation might have diverged as it contains information about new or altered features for the next major release. So you cannot just blindly copy over the state of the release branch into main after a patch release (but you can and should after a major release).