CI and releases
main is the only long-lived development branch; release/x.y branches exist only for hotfixes
of a released version (see Hotfix). Work happens on short-lived branches (or forks) and
lands via pull request, see CONTRIBUTING.md; CI runs
fmt, clippy and the test suite on Linux, and builds and tests the Windows version too —
cross-compiled on the Linux runner with cargo-xwin,
the tests running under Wine through cargo-nextest, one process per test.
fmt and clippy run first in a job of their own; both test jobs wait for it, so a lint failure
stops the run within minutes. The lint job also checks the lockfile for what only the release build
compiles: dlss_wgpu’s bindgen, which needs the DLSS SDK, fails on a syn/prettyplease
pair from two different syn majors (tools/ci/check_lockfile.py). macOS is not built for now: it would need Apple hardware.
Release channels
Section titled “Release channels”| Channel | Built from | Started by | Version |
|---|---|---|---|
| nightly | main |
hand, Run workflow | 0.2.0-nightly.20261119+5f7333f |
| prerelease | main or release/x.y |
tag v0.2.0-alpha.1, -rc.1 |
0.2.0-rc.1 |
| stable | main or release/x.y |
tag v0.2.0 |
0.2.0 |
All three go through the release workflow, which builds
the simulator, the route editor and the vehicle editor for Linux and Windows — Windows
cross-compiled like in CI, macOS not released for now, the signal editor built from source —
packs each together with mods/ and the licence, and attaches the archives to a Forgejo
release. Nightlies and every tag with a - are published as prereleases.
The Windows release also carries …-symbols.zip: the PDBs of the three executables, built
with line tables. They are what turns a crash dump from a player into function, file and
line — and they only match the exe of the very same release, so a dump is resolved with the
symbols archive of the version the player ran. Players never need it.
Until the first stable release the real releases are prereleases (-alpha.N, then
-beta.N); release candidates and stable versions are the same steps with another suffix.
Versions
Section titled “Versions”mainalways carries the next version. Right afterv0.2.0is tagged, a pull requestchore(release): start 0.3.0raisesworkspace.package.versionin Cargo.toml. A nightly then reports0.3.0-nightly…, newer than the last release and older than the next one; the workflow refuses a nightly whose version is already released.- Before 1.0 a breaking change to the mod format, the save files or the network protocol
(
feat!:, see CONTRIBUTING.md) raises the minor version, everything else the patch version. From 1.0 on, plain SemVer. - What a binary reports — the main menu’s footer, the editors’ About dialog — comes from
build-info: the release workflow setsCONNECTED_RAILS_VERSION, any other build reports0.2.0-dev. A nightly never editsCargo.toml.
Nightly
Section titled “Nightly”Actions → Release → Run workflow on main. Started from any other branch, the
workflow stops before it builds. The nightly is tagged nightly-<date>-<commit> on the
commit it built — deliberately not v*, so it neither triggers nor cuts short a real
release — and the newest ten are kept; older ones are deleted together with their tags.
Release and prerelease
Section titled “Release and prerelease”Bump workspace.package.version in a pull request (chore(release): 0.2.0-rc.1), then tag
the merged commit:
git tag v0.2.0-rc.1 && git push origin v0.2.0-rc.1 # prereleasegit tag v0.2.0 && git push origin v0.2.0 # releaseThe tag’s version must match Cargo.toml, otherwise the workflow stops before it builds.
After a stable release, bump main to the next version.
Hotfix
Section titled “Hotfix”A fix for a released version, without everything main has gained since:
main ──●──●──●──fix──●──●──▶ (already 0.2.0) │ ╎ cherry-pick -x v0.1.0 ╎ └─ release/0.1 ──fix──●──▶ v0.1.1 chore(release): 0.1.1- Branch from the tag — once per minor line, the first time it needs a fix:
git switch -c release/0.1 v0.1.0 && git push origin release/0.1. Every later hotfix of that line (0.1.2, 0.1.3, …) goes onto the same branch. - Fix
mainfirst, in an ordinary pull request. Then bring the squashed commit over withgit cherry-pick -xin a pull request againstrelease/0.1, labelledbackport/0.1. That way no fix goes missing from the next version. Only when the code no longer exists onmainis the fix made on the release branch alone — the pull request says why. - Bump the patch version on the release branch (
chore(release): 0.1.1);mainstays at its version. - Tag
v0.1.1onrelease/0.1and push it.
A hotfix changes neither the network protocol, nor the save files, nor the mod format — a
change to one of those is a minor release. A broken prerelease is fixed by the next one
(rc.1 → rc.2), a broken nightly by the next nightly. Only the newest minor line gets
hotfixes: once 0.2.0 is out, release/0.1 is frozen.
release/* branches are protected like main (repository settings → Branches): pull
requests only, CI green. CI runs on them as on main.
Release notes
Section titled “Release notes”tools/ci/release-notes.sh writes them: one line per pull
request — its title, linked — grouped into breaking changes, features, fixes, performance
and the rest by the conventional-commit prefix. They count from the nearest earlier release
of the right kind: a stable release from the previous stable one (v0.2.0 lists everything
since v0.1.0, v0.1.1 only its fixes), a prerelease from the previous v* tag, a nightly
from the previous nightly or release. Release Notes Assistant, used before, stops at the
nearest tag of any kind and reads v0.2.0-rc.1 as v0.2.0, which nightlies break.
Documentation
Section titled “Documentation”Each release line gets its own version of the documentation site: the
docs workflow runs on the same v* tag, rebuilds the
whole site and publishes the newest tag of each line under /<major>.<minor>/ —
v0.2.0-rc.1, v0.2.0 and v0.2.1 all end up in /0.2/, each replacing the one before.
main is published as /nightly/, rebuilt on every push that changes docs/. Documentation fixes for a
released version go to release/x.y like any hotfix and appear with the next tag.
Announcements
Section titled “Announcements”Once the release is published, the workflow posts it to Discord
(tools/ci/discord-announce.sh): an embed with the title,
the release notes — cut at a line below Discord’s limit, the rest behind a link to the
release — and direct download links for Linux and Windows. Nightlies, prereleases and stable
releases get their own label and colour; mentions are switched off, so no pull request title
pings anyone. It needs a channel webhook (Discord: channel settings → Integrations →
Webhooks) as a repository secret:
DISCORD_WEBHOOK_URL— every release.DISCORD_NIGHTLY_WEBHOOK_URL— optional, nightlies go there instead, e.g. to a channel of their own.
Without a secret the step says so and the release goes on. A failed post only marks the step,
never the release, which is out by then. This is deliberately not a Forgejo webhook of type
Discord: that one would also announce every old nightly the cleanup deletes. To check the
message without sending it: DRY_RUN=1 tools/ci/discord-announce.sh nightly <tag> <title> notes.md <release url> <archives…> prints the payload.
Dependency updates come from Renovate, which a
scheduled workflow runs every Monday: one pull request
for the crates, one for the workflow actions, one for the npm packages of the
documentation site (docs/package.json). It needs two repository secrets —
RENOVATE_TOKEN, an access token of the account the pull requests come from, and
RENOVATE_GITHUB_COM_TOKEN, a read-only github.com token for looking up actions and
changelogs.