station-master-startos/UPDATING.md

Updating the upstream version

Station Master is built from a git submodule at station-master/ (tracking Jesse.Markowitz/station-master, a self-hosted Gitea repo — this is Jesse's own game, not a third-party upstream, but it is packaged the same way: Dockerfile builds whatever commit the submodule points at, with no pinned dockerTag in the manifest. The submodule pin is the version.

Station Master tags its releases (v0.5.1, …) at the commit that bumped package.json. Nothing else about this package should need to change for a bump — not the Dockerfile, not main.ts, not the manifest — only the submodule pin and this package's own version (below).

Determining the upstream version

cd station-master && git fetch --tags && git tag -l --sort=-v:refname | head -5

The current pin is the submodule's checked-out commit:

git submodule status station-master

Applying the bump

cd station-master && git fetch --tags && git checkout v<new version>
cd .. && git add station-master

Then set this package's version in startos/versions/current.ts to the same number, as <tag>:0 — versions.md's consistency checklist requires the upstream half to match the submodule tag exactly, so v0.5.3 becomes 0.5.3:0. Give it release notes naming what changed for a player, then rebuild (make). Raise the :0 instead, leaving the upstream half alone, when the change is packaging-only and the bundled game has not moved.

The initial release shipped as 1.0.0:0 — the scaffold's placeholder, left in by mistake while the game was at 0.5.1. It was corrected to 0.5.2:0 before the package was ever published anywhere, which is the only reason a downgrade was harmless: 0.5.2:0 sorts below 1.0.0:0, so an installed copy had to be removed rather than updated over.

Building a test package from work that is not pushed yet

The Dockerfile copies station-master/ out of the build context, so what is packed is whatever is in that directory — the submodule's pin only matters for reproducibility, not for make. That is what makes it possible to put a build on a test box before the game is committed, tagged or pushed, which is how v0.7.0 was played before release:

# point the submodule at a local commit that exists nowhere else yet
cd station-master && git fetch --no-tags /path/to/station-master main && git checkout --detach FETCH_HEAD

# or, for work that is not even committed, copy the working tree in
rsync -a --delete --exclude .git --exclude node_modules --exclude dist \
      /path/to/station-master/ station-master/

cd .. && make x86 && make install

Move the DOWNSTREAM digit for each test build — 0.7.0:1, :2, :3. StartOS installs an update, not a re-install, so a rebuild at the same version has nothing to install over; and the downstream half is exactly the right one to move, since the upstream game has not been released again between two test packs. Whichever digit the box ends up on is the one the real release should carry: publishing a lower one afterwards is a downgrade the box will refuse.

Before committing the wrapper, put the pin back on a real tag — a submodule pointing at a commit that only exists on one machine is a package nobody else can build:

cd station-master && git fetch --tags origin && git checkout v<version>
cd .. && git add station-master

The pack's git stamp says -modified for the whole of this, which is the flag that a build came from a dirty tree. Never publish one of those.

---

If the jump carries a multiplayer protocol or persistence-format change (check the game repo's CHANGELOG.md and docs/architecture/multiplayer.md), read it before bumping: a running server's saved games are stamped with engineVersion and refuse to resume under a mismatched one (src/server/index.ts in the game repo) — nothing in this package works around that, so an in-progress game must finish (or be accepted as lost) before an incompatible bump.