The Release Process

The developers of Freeciv21 release new versions of the software following a cadence. The cadence is loosely defined as: 30 non-documentation pull requests (PR’s), 200 commits, or 60 days, whichever comes first. We use the term “loosely” as there is a large amount of discretion with regard to the cadence. We can speed up a release at any time to fix a nasty bug or slow a release down to get in a PR a developer is really close to completing and wants it in the next release. However, we do aim to release around 6 to 8 times per year.

Pre-releases are done from the master branch, while release candidates and stable releases use the stable branch, which contains bug fixes backported from master. See the dedicated page for how this is done.

These are the general steps to prepare and finalize a release:

  1. A release manager will open a draft release notes page from: https://github.com/longturn/freeciv21/releases. The easiest way to do this is to copy the contents of the last release, delete the bullet points, and add a single bullet of * Nothing for this release to each section. DO NOT add a tag at this time. This prevents an accidental release.

  2. A release manager will update the draft as PR’s are committed to the repository to help keep track of the release cadence progress. As PR’s are added to sections the * Nothing for this release is removed.

  3. As PR’s are added to the draft release notes, pay attention to the contributor. If a new contributor has opened a PR, call it out — “With this release we welcome @[GithubID] as a new contributor (#[PR])”

  4. Multiple PR’s can be combined on a single bullet line. Documentation updates are often done this way.

  5. When we are getting close to crossing one of the release candidate thresholds, the release manager will post to the #releases-project channel in the LT.DEV section on the Longturn Discord server. The main purpose of the post is to alert the developers of a pending cadence threshold and to gauge if we need to delay in any way or if we are good to proceed as normal.

  6. A release manager or another regular contributor will update the vcpkgGitCommitId value in the CI/CD build file (.github/workflows/build.yaml). Grab the Commit ID of the most recent release from https://github.com/microsoft/vcpkg/releases. Commit and push a PR. Ensure all of the CI/CD Action runners complete successfully.

  7. If the new release is a change from the dev, alpha, beta, candidate, or stable release series, there are some file updates needed:

    • .github/workflows/release.yaml — In the snapcraft section, change the release flag: edge for Dev or Alpha, beta for Beta, candidate for the RCs, and stable for Stable.

    • dist/*.metainfo.xml.in — At the bottom in the releases section, change the type value. Use development for Dev, Alpha and Beta, candidate for the RCs, and stable for Stable.

  8. When it is time, the release manager will finalize the release notes and ask for an editorial review in the #releases-project channel. Updates are made as per review.

  9. If the release will be the first release candidate towards a stable release, the release manager will:

    1. Tag the stable branch at HEAD with a -final tag for the old stable release.

    2. Remove branch protections from the stable branch in the repository settings.

    3. Delete the existing stable branch on the repository’s branches page.

    4. From the same page, create a new stable branch from master.

    5. Restore the stable branch protection setting.

    6. Update cmake/AutoRevision.txt with the hash of the last commit in master and set a development version (v[major version].[minor version]-dev.0). Open a PR for this change to master. This way, development builds from master will immediately use the version number of the next stable until we release a new unstable release.

  10. The release manager will update the GitHub STORE_SECRETS secret for the snap package. Refer to Packaging Freeciv21 for more information. It is very important to do this step just before the release is committed to GitHub as it does expire after some time.

  11. If the release is a release candidate for a stable release, the release manager will make sure that the Target branch in the release draft is set to stable.

  12. The release manager formats the release tag. For this, they checkout the target branch locally and create a local tag with git tag following the expected format, then run the configure step (cmake -B build) to check that it works as expected.

    The format of the tag is v[major version].[minor version]-[pre-release name].[number] for pre-releases and v[major version].[minor version].[patch version] for stable versions. For example: v3.0-beta.6 or v3.1.0. The format is very important to the build configuration process.

    Note

    More information on our version numbering format. We follow a relatively standard Major Version, Minor Version, Patch Level Number format, especially for our stable releases. However we allow some text — [release name] — to be included for our non-stable releases. The available [release name] values are: dev, alpha, beta, rc, or patch. Stable releases follow the well known x.y.z format and non-stable releases use the x.y-text.z format.

  13. The release manager then adds the tag to the release notes page and clicks Publish Release.

  14. After a few minutes the continuous integration (CI) will open a PR titled Release Update of AutoRevision.txt. The release manager will open the PR, click on the Close pull request button, and then click Open pull request button. This is a necessary step to handle a GitHub security feature. GitHub requires a human to be involved to merge CI created PRs.

  15. While inside the Release Update of AutoRevision.txt PR, the release manager will enable an automatic rebase and merge.

  16. The release manager will open an issue titled Review workarounds after <version> release with the following text:

    We should review the workarounds in the source code and check that they are still needed. Some workarounds are documented here: Workarounds.

  17. When all the CI actions are complete, the release manager will make a post in the #news-channel on the Longturn.net Discord server.

  18. The release manager mentions user @panch93 on Discord #releases-project channel so he can update the Arch AUR with the latest release.

  19. The release manager mentions user @blabber on Disord #releases-project channel so he can update the FreeBSD with the latest release.

Behind the Scenes

This section describes how the Continuous Integration (CI) / Continuous Delivery (CD) is setup for Freeciv21 on GitHub.

GitHub’s CI/CD is called Actions and is enabled via YAML files in this directory in the repository: https://github.com/longturn/freeciv21/tree/master/.github/workflows.

There are two files that are integral to the release process: build.yaml and release.yaml. The build.yaml file is the main CI/CD file. It is what runs all of the action “runners” every time a PR is opened or updated with a commit to the repository. You can see the status of the runners on the actions page at: https://github.com/longturn/freeciv21/actions. When a release is published, we have code in the file to upload the installers generated by the operating system runner. In this file we generate the binary packages for Windows x86_64 (64 bit), Debian, and macOS. The release.yaml file is triggered when we publish a release. This file generates the .zip and .tar.gz source archives as well as the Windows i686 (32 bit) installer. All of these files are automatically uploaded and attached to the release notes page as assets at the bottom.