# 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.

## 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:

```bash
# 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:

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