Skip to content
Connected RailsConnected Rails

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.

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.

  • main always carries the next version. Right after v0.2.0 is tagged, a pull request chore(release): start 0.3.0 raises workspace.package.version in Cargo.toml. A nightly then reports 0.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 sets CONNECTED_RAILS_VERSION, any other build reports 0.2.0-dev. A nightly never edits Cargo.toml.

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.

Bump workspace.package.version in a pull request (chore(release): 0.2.0-rc.1), then tag the merged commit:

Terminal window
git tag v0.2.0-rc.1 && git push origin v0.2.0-rc.1 # prerelease
git tag v0.2.0 && git push origin v0.2.0 # release

The tag’s version must match Cargo.toml, otherwise the workflow stops before it builds. After a stable release, bump main to the next version.

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
  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.
  2. Fix main first, in an ordinary pull request. Then bring the squashed commit over with git cherry-pick -x in a pull request against release/0.1, labelled backport/0.1. That way no fix goes missing from the next version. Only when the code no longer exists on main is the fix made on the release branch alone — the pull request says why.
  3. Bump the patch version on the release branch (chore(release): 0.1.1); main stays at its version.
  4. Tag v0.1.1 on release/0.1 and 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.

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.

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.

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.