Files
Triforce-Source/docs/versioning.md
ruckus7382sfgsgdf 34b3683441 Triforce v0.2.0
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 19:32:48 -06:00

9.7 KiB

Versioning and releases

Hookshot follows Semantic Versioning 2.0.0 and the conventions of semantic-release. The current version is 0.1.0.

The git tag is the only source of truth. No file carries a version that has to be edited for a release: the game reads the tag through nx2/version.py, and the builder and the AppImage are stamped from the same tag when they are packaged.

The version number

MAJOR.MINOR.PATCH, with an optional prerelease suffix: 0.1.0, 0.2.0, 0.2.0-rc.1. A release is tagged v0.1.0: the v belongs to the tag, not to the version. Build metadata is not used in tags.

One version covers the whole project: the game (hookshot.exe / hookshot), the Vulkan back end, the lift pipeline and its scripts, Hookshot Builder and the Linux AppImage. They are built from the same commit and released together, so they never carry different versions.

The "public" surface the rules protect is the command line of make_game.py and the builder, the RX_ and HOS_ switches, the files a build writes into a game folder (hookshot_options.ini, hookshot_env.txt, language.txt, hookshot_version.txt), saves, and the format of hookshot_log.txt. The C sources and internal headers are not an API and may change in any release.

Commits decide the version

Releases are computed from the commits on the release branch since the last tag, so commit subjects must be Conventional Commits:

type(scope): description
type(scope)!: description        (a breaking change)

scope is optional. A ! before the colon, or BREAKING CHANGE: / BREAKING-CHANGE: in the commit body, marks a breaking change. The description is written as an imperative ("Stop scanning...", "Fix the..."), because it becomes the changelog line.

Commit Next version
any commit with ! or BREAKING CHANGE: major (0.1.0 -> 1.0.0)
feat minor (0.1.0 -> 0.2.0)
fix patch (0.1.0 -> 0.1.1)
perf patch
revert patch
docs, refactor, style, test, build, ci, chore no release

git revert writes Revert "...", which is not a Conventional Commit: use git revert --edit and write the subject as revert: ..., or the revert makes no release.

A release takes the highest bump among its commits. Merge commits are ignored, and a commit with [skip release] or [release skip] in its message is left out of the analysis. chore(release): 0.2.0 [skip ci] [skip release], the commit the release itself makes, is not a release (the notes in its body can mention a breaking change).

There is no manual version bump. If a change should not make a release, use one of the types in the last row; if it should, use feat or fix.

0.x and 1.0.0

semantic-release does not treat major version zero specially: a breaking change is a major bump even from 0.1.0. This is deliberate. Its documentation says that SemVer's different rules for 0.x are out of scope, and it recommends 1.0.0 as the first release.

Hookshot starts at 0.1.0 anyway, because the first versioned release is not stable. That tag is made once by hand (see below); after it, the release workflow is the only thing that creates tags. Consequence: the first breaking change merged to main releases 1.0.0, not 0.2.0.

1.0.0 means the public surface above is considered stable. Until then, keep breaking changes on the next branch and release them there as 1.0.0-rc.N, or accept that the release that carries one becomes 1.0.0.

Branches and the release workflow

Branch Purpose Version
main stable releases vX.Y.Z
next release candidates vX.Y.Z-rc.N

Every push to main or next runs the Release workflow. It:

  1. finds the last release tag and the commits since it;
  2. takes the highest bump in the table above;
  3. runs scripts/changelog.py to put the new entry at the top of changelog.txt;
  4. commits changelog.txt as chore(release): <version> [skip ci] [skip release];
  5. tags the release commit. The tag starts the Linux AppImage and Windows builder workflows: the first to finish makes the GitHub release, and each attaches its files (the AppImage; HookshotBuilder.exe, the setup, and hookshot-setup.txt, with the new parts in the builder-parts release). scripts/release_upload.sh is shared by both.

A merge with no releasable commit (only docs, chores, and so on) makes no release. A release is never edited by hand, never re-tagged and never deleted. Require the Game-free source regressions workflow on main and next (branch protection): the release then runs for a commit whose tests have passed.

The workflow pushes back to the repository, so it needs a token with contents: write that may bypass main's branch protection. Use a RELEASE_TOKEN secret (a fine-grained personal access token) rather than the built-in GITHUB_TOKEN: a tag pushed with GITHUB_TOKEN does not start another workflow, and the Linux AppImage and Windows builder workflows publish the release from the tag. With only GITHUB_TOKEN, build both with workflow_dispatch and create the release by hand.

The first tag: 0.1.0

semantic-release's first release is 1.0.0 when it finds no tag. To make 0.1.0 the first version, tag the merge commit that introduces this scheme once:

git tag -a v0.1.0 -m "Hookshot 0.1.0"
git push origin v0.1.0

The Release workflow does nothing while no version tag exists, so the merge cannot release 1.0.0 first. The pushed tag starts the Linux AppImage workflow, which creates the 0.1.0 GitHub release with the AppImage attached; create the release by hand if you do not want to wait for it. The 0.1.0 entry in changelog.txt is written for that tag. After it, do not tag by hand.

Pre-releases

A release candidate is released from next with the same commands. semantic-release numbers it v0.2.0-rc.1, v0.2.0-rc.2, and so on; the GitHub release is marked as a prerelease and never becomes "latest". A prerelease is not written to changelog.txt: Factorio's parser accepts only major.minor.patch, and two release candidates share a base version. Its notes are in the GitHub prerelease. Merge next into main to release the final 0.2.0, whose entry lists every commit since the last stable tag.

Hotfixes

Branch from the release tag, not from main, when a fix must not include main's unreleased features:

git switch -c fix/crash v0.1.0

Commit with fix: ... and open a pull request to main. If main has no unreleased feature commits, the release is a patch. The project does not keep maintenance branches for older minor versions: only the newest release is supported.

Where the version appears

Place Where it comes from
git tag semantic-release; the source of truth
changelog.txt scripts/changelog.py during the release
hookshot_log.txt and the Insert menu nx2/version.py: HOOKSHOT_VERSION, then VERSION/version.txt, then git describe --tags --match "v[0-9]*"
hookshot_version.txt in a build the VERSION file written when the tools are packaged (nx2/make_game.py)
AppImage file name git describe --tags --match "v[0-9]*" (scripts/linux/appimage.sh)
HookshotBuilder.exe the MSBuild Version passed at publish time (dotnet publish -p:Version=<version>, the Windows builder workflow); the csproj's 0.1.0 is only the default for a local build

nx2/version.py also appends a fingerprint of the source files, (source 1a2b3c4d). It is not a version: it tells two builds of the same release apart, and it is the only identifier a build from a modified checkout has.

package.json and package-lock.json (if present) are the release tooling's, not the project's: package.json keeps the placeholder 0.0.0-development on purpose, and the tag remains the version. The game never reads them.

The changelog

changelog.txt follows Factorio's changelog format. Newest first, with a 99-dash separator before each version:

---------------------------------------------------------------------------------------------------
Version: 0.1.0
Date: 07. 11. 2026
  Features:
    - Something new.
  Bugfixes:
    - Something fixed.

The date is day. month. year (07. 11. 2026), as in Factorio's own changelog. Section names are indented two spaces, bullets four, there are no tabs or trailing spaces, and a section is omitted when it is empty. The version is always three numbers: a prerelease has no entry (see above).

Commit Section
feat Features
fix, revert Bugfixes
perf Optimizations
refactor Changes
breaking change Changes, as Breaking: ...
docs, style, test, build, ci, chore not listed

A stable release writes the entry. Do not renumber, reorder or rewrite a released entry; a correction is a new commit and a new release. The 0.1.0 entry was written by hand because the history before this scheme does not use Conventional Commits.

History

Tags from before this scheme (Release, amd, text-hotfix, and so on) are snapshots of the old workflow. They stay in the repository for history but are not releases: the tooling matches only v[0-9]* tags. v0.1.0 is the first versioned release.

Rules

  • Do not edit a version number in a file, move a tag or reuse a version.
  • Do not tag a branch other than main (or next for a release candidate).
  • Do not release from a dirty working tree; the release commit contains changelog.txt and nothing else.
  • Do not put game files, keys, builds or anything made from a dump in a release.