Test, Production and Personal

Starfarer runs in three installs on the development PC, so a change can never reach the shipped version, or the Captain's own daily assistant, untested.

	Test	Production	Personal
What it is	Where every change is made and tried first	What gets shipped: exactly what a new user gets	The Captain's own daily assistant
Folder	Starfarer-test	Starfarer-prod	Starfarer
Code	branch dev	branch main (a released version)	branch main (a released version, upgraded when the Captain says)
Port	3011	3012	3010
Label	Test (badge on the Bridge and window)	Production (badge, on this PC only)	none
Data	a copy of Personal's, refreshed when asked	starts empty ("Welcome aboard"), like a new user	the real crew, memory, personas, add-ons, tool servers
Modules	anything being worked on	default (built-in) modules only	whatever the Captain adds

All three share Ollama and the graphics card: run them at the same time only when needed.

What's personal lives in data, never in code. The Captain's personas, voices, add-ons and tool servers (Home Assistant) belong in Personal's data/ folder (or an add-on there), not in the code that ships.

Where the code lives

• Starfarer-test is where commits are made (dev), where main is advanced on a promotion, and what pushes to the git server (origin): git push origin dev main --tags.
• Starfarer-prod and Starfarer pull released versions from Starfarer-test (remote test).

Rules

• Every change goes to Test first. Production and Personal only change by a promotion / an upgrade.
• The Captain decides what gets promoted and when Personal upgrades.
• Production ships the default modules only; an add-on becomes a default module only when the Captain says so.

Promoting Test to Production

1. In Starfarer-test: all tests pass (.venv\Scripts\python -m pytest), and the change was tried on the Test Bridge (port 3011).
2. Set the version in starfarer/__init__.py (drop .dev0), add the release to CHANGELOG.md, commit on dev.
3. Still in Starfarer-test:

   git checkout main
   git merge --ff-only dev
   git tag -a v0.2.0 -m "Starfarer 0.2.0"
   git checkout dev
   

   Then set the next version on dev (0.3.0.dev0) and commit.
4. In Starfarer-prod: git pull test main, then restart it. Check the first-run experience there.
5. Push: in Starfarer-test, git push origin dev main --tags.

Nothing personal ships

The code, docs and tests carry no one's personal details: no names (apart from the copyright and credit lines), home, town, family, pets, job, accounts, machine names, addresses or other projects. Tests use made-up people and places ("Sam" in "Springfield"). Anything about one household (its place names, its devices, its tool servers) is that install's data (data/), never code.

Before every release, scan for the developer's own details. The word list is private, so it lives in the data folder (data/release-scan.txt, one pattern per line, never committed), and the scan is:

git grep -n -I -i -E -f data/release-scan.txt -- . ":!LICENSE" ":!LICENSES" ":!sdk/LICENSE"

The only hits allowed are the copyright and credit lines (NOTICE.md, CLA.md, pyproject.toml, the licenses, the README's credits).

Publishing a public copy

The private repo keeps the full working history; older commits hold notes and test data from before the cleanup. A public repo therefore never gets that history: it starts from one fresh commit of a release (the files of main at its tag, without .git), and each later release is one more commit on top. Commit there with a public address (a no-reply address), not a personal one.

Upgrading Personal

When the Captain says so: in Starfarer, git pull test main (or git checkout v0.2.0), run install.bat if the release notes say packages changed, and restart. Check the release notes for anything that moved from code into data (a household's own settings): add it to Personal's data/ before restarting.

Refreshing Test's data from Personal

Stop Test, copy Starfarer\data\ over Starfarer-test\data\ but keep Test's settings.json (port 3011, label Test), then start Test.