Contributor Workflow
Conventions for landing changes in Underroot: how work is branched and reviewed, the one file you must never blindly revert, and the secrecy rules around redemption codes. Follow them to keep the repo clean and avoid leaking datamine-sensitive content.
Branch and PR per item
Each unit of work gets its own branch and its own pull request. Keep changes scoped — one feature, fix, or balance pass per branch — so reviews stay focused and history stays readable. The maintainer (Mike) merges pull requests. When explicitly asked to merge, use a merge commit and delete the branch:
gh pr merge --merge --delete-branch
After merging, verify you are back on main and it contains the change before moving on. Do not merge on your own initiative; wait for the go-ahead.
The project.godot backup rule
project.godot carries uncommitted local tweaks the maintainer keeps in the working tree. This makes one common command dangerous:
Never run
git checkout -- project.godotto "clean up" — it discards those local tweaks.
The one legitimate exception is the smoke test, which appends a single temporary [autoload] line and reverts exactly that. When you need to make a temporary edit to project.godot yourself — for example adding a temp autoload so a scene gets parsed or the smoke test can run — copy-backup the file first and restore from the copy afterward, rather than reverting through git:
cp project.godot project.godot.bak
# ... append temp autoload line, run headless check ...
cp project.godot.bak project.godot
rm project.godot.bak
This restores the exact pre-edit contents, including any uncommitted tweaks, without touching git history.
Redemption code secrecy
Underroot ships one-time redemption codes (handled by CodeManager, stored in data/codes.json as SHA-256 hashes of the uppercase code — never plaintext). Two rules protect them:
- Strip dev and cheat codes before merging to main. Any unlock shortcut or cheat code added for local testing must be removed from the branch before it lands. The data validator enforces the hash-only format for
codes.json, but self-review is what keeps testing shortcuts out. - Keep literal codes out of commit messages and PR descriptions. Git history and PR text are public/datamine-visible. Never write the plaintext of a redemption code in a commit message, PR title, or PR body. Refer to a code by what it unlocks, not by its literal string.
See Adding a Redemption Code for the hashing procedure.
Subagent branch safety
The working directory's branch can change mid-session — the maintainer may switch branches while an agent is mid-task. Any automated contributor (subagent) must verify the current branch immediately before committing, not rely on the branch that was checked out when the task began. Confirm you are on the intended branch (git branch --show-current) as the last step before git commit, so work never lands on the wrong branch.
Before you open a PR
Run the three local verification gates and confirm each passes — Parse-check clean., DATA OK, SMOKE PASS. Run the data validator after any data/*.json edit specifically. Details and exact commands are in Verification and CI. Runtime behavior beyond what the gates cover still needs a visual check in the Godot editor.