# Updating the upstream version

Station Master is built from a git submodule at `station-master/` (tracking
[`Jesse.Markowitz/station-master`](https://draco.local:53871/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

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

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

```bash
git submodule status station-master
```

## Applying the bump

```bash
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.

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.