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

```text
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.godot` to "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:

```text
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](/docs/underroot/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](/docs/underroot/verification-and-ci). Runtime behavior beyond what the gates cover still needs a visual check in the Godot editor.

## Related

- [Verification and CI](/docs/underroot/verification-and-ci)
- [Codes and Redemption](/docs/underroot/codes-and-redemption)
- [Adding a Redemption Code](/docs/underroot/adding-a-redemption-code)
- [Repository Layout and Boot Flow](/docs/underroot/repository-layout-and-boot-flow)