Skip to content
This repository has been archived by the owner on Jan 5, 2024. It is now read-only.

Cf/460 Create a release workflow to publish new source build artefacts #466

Conversation

traunts
Copy link
Collaborator

@traunts traunts commented Dec 11, 2022

See #460 for a summary, this will be updated once I've finished drafting it.

This PR introduces changes to the existing build workflows that facilitate automatic versioning and release management of the Source executables. It achieves this through the tool semantic-release, which executes the following steps:

  1. Analyse the commit history between the current HEAD ref and the last release (determined by the git tags on the release branch) to determine the new release version, following semantic versioning standards.
  2. Generate a set of release notes based on the content of any commits that increment the version
  3. Commit a new tag to the release branch (and any changes to version references in the codebase) that labels that ref as a new release version.
  4. Publish a new GitHub release containing any build artefacts, source code and the generated release notes.

This workflow is triggered by any push to the master or development branches. Pushes to master will publish a new main release, and label it as the latest official. Pushes to development will publish a prerelease and label it as such.
This allows us to easily distribute dev builds of the source engine while maintaining the official status of the master branch.

This PR includes changes to the current build workflow and adds relevant release config files to enable that.

It also renames and adds a concurrency group to the CI workflow, so new changes to a PR branch will cancel any outdated workflow runs on that PR


Critical Information Summary:

  • To determine a version and generate release notes, semantic-release requires that the commits it analyses follow the conventional commits format.

    To bump a version and trigger a new release, at least one commit in a batch of changes must match this format, and be of type fix, feat, or indicate breaking changes with a ! following the type or BREAKING CHANGE: in the commit body.

    Similarly, only commits matching this format will appear in the release notes. When they do they'll be grouped by their type.

    Optimally, all commits that patch the game, add new features or break mods should be formatted like this (as the changes are made) to ensure that all the relevant changes are well captured. Realistically, this is a change to how devs work, and no one likes that, so the absolute minimum requirement is that at least one commit in a batch (For example, the merge commit from a PR) matches the required format.
    This may prove advantageous, as you don't have to worry about junk/testing commits, just formatting the important ones that make changes.

    Note: Failing to meet this requirement won't actually break anything, it just won't bump the version or publish a new release. It may, however, let undocumented breaking changes slip through in later releases.

  • Automated versioning requires that the project adheres to the semantic versioning standard, and has published a v1.0.0 release.

    To distinguish between major/minor/patch versions, and importantly, to use semantic-release, the project must either have an existing major version published or start tagging with v1.0.0. semantic-release uses git tags to detect the current version and to judge which commits to include in its analysis when generating a new release version. Without a valid tag containing a semver ${version}, the workflow won't work.

    The workflow will automatically tag and publish prereleases with the format v${version}-pre.${X} on pushes to development, and full releases in the format v${version} on master.

    See https://semantic-release.gitbook.io/semantic-release/support/faq#can-i-set-the-initial-release-version-of-my-package-to-0.0.1
    See the reference fork below for examples. In my case this published a v1.0.0-pre.1 once merged to dev and then a v1.0.0 in master

Other Notes:

TODO:

  • Windows and Linux build jobs should really be turned into reusable actions, as they're duplicated across these workflows. Need to be configurable to work on different build targets (debug/final). I'll openissue™️ for this later, not in scope.
    Make existing build workflows reusable #470
  • Might need to narrow the environment variable scope for the GH_TOKEN down to just the release steps, better practice. I'll implement it once this is out of the draft stage.
  • Add some more comments to the release workflow clarifying steps (maybe, most are well-named)

Examples of these changes and generated releases can be found here in a testing fork.

Feel free to push to the master/development branches of this forked repo to test how releases are created.

traunts and others added 12 commits December 5, 2022 21:31
Renamed Workflow & workflow file.
Added missing names to the two build jobs.
Formatting (indentation)
created a unified `build.yaml` workflow file, containing each of the platform-specific build jobs
…existing-build-workflows-to-trigger-releases

Cf/461 Prepare existing build workflows to trigger releases
This lays the groundwork for a release workflow using Semantic Release.
Adds a precursor job to both platform-specific build jobs that determine the release version and set it as a GitHub environment variable.
This uses a dry-run of semantic-release with the export plugin.

Adds placeholder steps to both workflows to apply this version before building.

Updates `actions/checkout` to `@v3` in both build jobs.

Adds a new `release` job, dependent on both builds, that publishes a new GitHub release with the built artifacts.
Contains placeholder to increment version (so that it can be committed with the new version tag)
Calls semantic release to achieve this, config as yet unset.
Release workflow uses a regex replace to write the new game version to the `c_GameVersion` variable in `System/Constants/h`
Applied pre-build in both jobs, and again to be committed in the release job.
This file specifies the branches to trigger releases on, and required plugins
Designates `System/Constants.h` as the committed version file, and all artifacts downloaded to a `release/` dir to be published.
…s' into cf/460-create-a-release-workflow-to-publish-new-source-build-artefacts
@traunts traunts added enhancement New feature or request refactor Code needs to be refactored labels Dec 11, 2022
@traunts traunts linked an issue Dec 11, 2022 that may be closed by this pull request
6 tasks
@traunts
Copy link
Collaborator Author

traunts commented Dec 11, 2022

This PR changes the required checks by renaming the workflow and jobs and will require modification of those settings to be able to merge.
Otherwise, it'll flag it as expecting a report from a required check that no longer exists in the head of the PR, so will never run (I've had this issue before, needs Admin oversight)

NOTE: There's a 40-second window during release where cancelling the job will majorly fuck the release & git history.
Raise this issue with the team in discussions!
Regex works correctly and works cross-platform thanks to the shell specifier.
Remove the unneeded env workspace prefix.
Needs to be turned into a GitHub Action.
Add `get-version` as a requirement to the `release` job to access its outputs.
The `npm install` command pulls `@latest` by default.
By forcing these to use a set version we avoid accidentally pulling a new major version and introducing breaking changes.
Note: This adds it to all jobs in the workflow, maybe revise it to only target steps in the jobs that require them.
Add conditional execution to jobs following the one that determines the new version, so they are discarded from the queue if not needed.
Update the `.releaserc.json` file to match current prerelease tagging.
Disable release comments on issues / failed build issues triggered by publishing a new release.
@traunts traunts marked this pull request as ready for review December 12, 2022 07:03
@traunts traunts marked this pull request as draft December 14, 2022 04:01
@traunts
Copy link
Collaborator Author

traunts commented Dec 14, 2022

Deferred until the repo is in a more suitable state to work with this one (monorepo or something, won't work easily without being able to track changes to both projects).

@traunts traunts closed this Dec 14, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
enhancement New feature or request refactor Code needs to be refactored
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Create a Release workflow to publish new Source build artefacts
1 participant