Skip to content

New Release Procedure

Jump to bottom Edit New page
JohnAFernandez edited this page Jan 14, 2023 · 22 revisions

Overview

To help streamline how a new release would be handled here is a small list with the necessary steps:

  1. Create a forum post saying that we plan on a new release soon which contains a call for modders and users to bring breaking bugs or critical missing features to our attention so those can be fixed or added before the release. Features would only be added for mods that are close to completion.
  2. Once those issues have been resolved (or none have been reported) we add a RC-1 tag for the latest commit on the master branch. Based on that commit the first release candidate build is compiled.
  3. If bugs are found those are fixed and a new RC tag is created and new builds are posted. GOTO 3.
  4. If no bugs are reported the current release candidate will be relabeled as the final release and that commit is tagged as the release version.

Details

Since this an involved procedure require collaboration between play testers and developers to resolve bugs, it would be beneficial to set some sort of dates and scheduling so that folks can prepare their daily work lives should they need or want to. With that in mind, here are some "firm" policies regarding the New Release Procedure:

  • The Release Cycle begins on the last Friday of a business quarter, with the next month dedicated to bug hunting.
    • Should there be any features that are not ready for merging, they are turned into a PR draft and labeled with "Waiting for Stable"
    • There is a hard time limit of 1 week to decide if a feature should be merged or not after the start of the cycle. After this time limit, it is pushed back after the release
  • Each week has one Release Candidate, published every Friday. This is so that, in theory, folks can use their weekends to help playtest and look for bugs.
    • There shall not be more than one RC per week unless special circumstances require it. The reasoning here is that, since this is a volunteer group, there is no guarantee that testers and developers will be able to test the changes on such short notice. The one-per-week limit also allows for contributors that don't have the typical weekend days off to participate without feeling left out or pressured.
  • The target date set on the Github milestone is when the cycle begins. Due dates don't work well with our volunteer organization because we can't guarantee qualified people will be available to go through with the RC.
  • The target date is set as the second to last Friday of the month.
  • All during the Release Cycle, new features will not be merged (unless they are critical to a mod's development) and instead only High Priority bugs, as determined by the Bug Triage Project, shall be considered.
    • Only High Priority bugs and their fixes determine if another Release Candidate is required. If there are no High Priority items that pop up (and subsequently resolved) after a Release Candidate becomes available, and at least one week but at most two weeks have passed, then that Candidate becomes Final.
  • Should a new bug occur at any point during the Release Cycle, it must be thoroughly diagnosed and prioritized accordingly before a new Release may be published. Crashes, Freezes, and Regressions due to changes between RC's will always be a High Priority item.
  • !!All bugfix PR's during a release cycle must have an attached issue!! This is so that potentially high-priority items don't slip through the Bug Triage project, since it is the primary means of determining if a Release Candidate is eligible for publishing as Final.

How to trigger a release cycle using Github Actions

  • Update changelog.md to include major changes (new features, significant behavior changes, etc.)
  • Update ci/post/release.mako to reference the previous release (not release candidate) thread in the forums
  • Commit with git add .
  • Push your changes to your fork, and create a PR for approval
  • Use the Trigger a Release workflow in the nightlybuild repository and fill out the proper fields
  • Ensure all builds have been built and packaged within the Build Release Package workflow] in the fs2open.github.com repository
  • Ensure success of the Post Release Builds workflow in the fs2open.github.com repository

How to trigger a release cycle using Git

  • Update changelog.md to include major changes (new features, significant behavior changes, etc.)
  • Update ci/post/release.mako to reference the previous release (not release candidate) thread in the forums
  • Create version_override.cmake to update the revision string used internally and on the forums.
  • Commit with git add . and git commit -m "Manual build commit"
  • Create an annotated tag: git tag -a release_<major>_<minor>_<build> -m "Build commit tag"
    • <major> is the last two digits of the year
    • <minor> is the quarter (even numbered)
    • <build> is the "point release" (usually 0)
    • Release candidates use the form of release_<major>_<minor>_<build>_RC<iteration> ex: release_22_0_0_RC5
  • Push with git push upstream --tags
    • This will create a tagged commit that is floating off of the master branch and trigger the Build Release package workflow
  • Ensure all builds have been built and packaged within the Build Release Package workflow] in the fs2open.github.com repository
  • Ensure success of the Post Release Builds workflow in the fs2open.github.com repository

!!WARNING!! The tag must not be a lightweight tag. Although the build process will still trigger, our publishing script will fail. GUI git integrations such as TortoiseGIT may prefer to use lightweight tags over annotated, so check the tag first before pushing.

Publishing Failures

In the case that the builds were successfully compiled and packaged, but failed to upload to the Release FTP, badged members need not re-run the build-release workflow. The manual override process is as follows.

  1. Go to the build-release workflow history

  2. Click on the most recent run of the workflow. Example:

  1. On the left hand side of the page that opens, note which Build Distribution job failed. In this example, the Windows x64 SSE2 job failed:

  1. Scroll down on the right hand side, find and download the release .zip (-builds-Win32 or -builds-x64) and debug .7z packages within the Artifacts group.

  2. If the packages were downloaded as .zip.zip or .7z.zip, you'll have to unzip them into their proper .zip and .7z forms.

  3. Go to the Release FTP

  4. Click the Pencil icon to the right of the release.

  1. Scroll down to the file list, and look for any files that have a icon to the side of them. These are the files that have to be deleted with the black X and then uploaded with the packages you had just gotten earlier

  2. Upload the missing packages by drag-and-drop into the box here, or click on the box to get the file upload dialog.

  1. Once the packages have been uploaded, click on Update Release

  2. Manually trigger the Post Release Builds workflow, using the tag name of release as it shows up in git. ex: release_22_0_0

Post Publishing

Once the release is properly published and the forum post and change log are finished, please link the forum post in the github release description, with a description of "Forum release page and change log". This is for issue #4131.

Point Release Cycles

Starting in October 2021, we're trying out release cycles for so-called "point releases." These are releases that are done between the normal scheduled releases and include only bugfixes and a few QoL adjustments. There are two styles of point release cycles, first of which is called "hotfix style" and the second of which is called "half cycle style."

The hotfix style is triggered whenever a high-priority bug is found after publishing a standard release, and is one that can not wait to be addressed by the next standard release. The selection of said bugs is at the discretion of the SCP. These bugs are marked as high priority, milestoned to a point release version (such as 21.4.1), and the point release cycle has a motus operende similar to standard cycles (release candidate on the weekend, up to two weeks of testing).

The half cycle style is triggered half-way between standard release cycles (2 months), and has a motus operende similar to standard cycles (release candidate on the weekend, up to two weeks of testing).

Both point release cycle styles will include only bug fixes, cleanups, refactors, and qualifying QoL features (as determined by the SCP). During the point release cycle, all qualifying changes may be included in the release, even ones that only address low-priority issues.

cc

Quick Links

External Links

Clone this wiki locally