Home Run Derby Wiki

Git and PRs

4 min read

Git and PRs

In short

Nobody pushes to main. Every change goes on a branch, then a pull request (PR) on github.com/gonzalezdan0315-sys/HomeRunDerby that a friend reviews. Locally, Claudio playtests every change in the dev folder before anything is pushed or a PR is opened, and he clicks Merge on GitHub himself.

How it works

flowchart LR
    A["git switch main<br/>git pull"] --> B["git switch -c feature/..."]
    B --> C["work in Unity<br/>commit"]
    C --> D["Claudio playtests<br/>in the dev folder"]
    D -->|signs off| E["git push -u origin<br/>branch"]
    E --> F["open PR<br/>fill the template"]
    F --> G["friend reviews<br/>Approve / Request changes"]
    G --> H["Claudio clicks Merge<br/>on GitHub"]

The team flow (CONTRIBUTING.md)

  1. git switch main, git pull, then a new branch: git switch -c feature/corked-bat-sound.
  2. Work in Unity, press Play, make sure it works. git add -A, git commit -m "...".
  3. git push -u origin <branch>, open the link Git prints (or GitHub’s Compare & pull request banner), fill in the template and request a review.
  4. The reviewer reads Files changed, can try it with git fetch and git switch <their-branch>, then picks Approve or Request changes under Review changes.
  5. Once approved, the PR is merged and the branch deleted.

Branch names: feature/... new stuff, fix/... bugs, content/... new upgrades, ballparks or pitchers, chore/... setup.

Unity rules from CONTRIBUTING: always commit .meta files with their asset; never commit Library/, Temp/, Logs/, UserSettings/ or .csproj / .sln (the .gitignore blocks them); one person per scene or prefab at a time; keep PRs small; big binaries go through Git LFS automatically (Unity Setup).

This team’s local rules

  • Never push to main, not even a one-line fix. If you are on main, branch first. GitHub can’t enforce this on the repo’s current plan, so it’s on trust.
  • Three folders, all worktrees of one repository (git worktree list from any of them shows them):
    • C:\Users\Claudio\Desktop\Code\HomeRunDerby is the dev folder: feature branches live here and this is the copy Claudio opens in Unity to playtest.
    • C:\Users\Claudio\Desktop\Code\HomeRunDerby-main is a git worktree on main, a read-only reference copy (this wiki is written from it). Don’t work in it.
    • C:\Users\Claudio\Desktop\Code\HomeRunDerby-batting is a worktree on feature/msb-batting (tracking origin), added on 2026-10-22 for the Mario-style batting work (#46). It is not auto-synced. A branch can be checked out in only one worktree at a time, so the dev folder can’t switch to a branch another folder holds.
  • Auto-sync of HomeRunDerby-main: a Windows Task Scheduler task named “HomeRunDerby-main sync” runs git -C C:\Users\Claudio\Desktop\Code\HomeRunDerby-main pull --ff-only --quiet every 15 minutes (and at logon), hidden through conhost --headless with GIT_TERMINAL_PROMPT=0, and appends a timestamp to %LOCALAPPDATA%\HomeRunDerby-main-sync.log. So the reference copy is at most about 15 minutes behind origin/main and nobody refreshes it by hand. If it looks stale, read that log first. A fast-forward-only pull refuses (and changes nothing) if someone committed in that folder, which is one more reason not to work in it.
  • Playtest before any push or PR. Commit locally, put the dev folder on that branch, Claudio plays it in Unity and signs off. Only then push and open the PR.
  • Claudio clicks Merge on GitHub. Claude Code opens the PR but never merges it.
  • No AI attribution in commit messages or PR descriptions.

The templates (.github/)

  • Pull request (pull_request_template.md): What does this change? (link the issue, “Closes #12”), which part of the game (tick boxes: Batting & Pitching, Run Structure, Upgrades & Shop, Ballparks & Scoring, Progression & Multiplayer, UI / visuals, Tooling / project setup), how you tested it, screenshots or clips, and a checklist: opens in Unity 6000.6.6f1 with no red Console errors, pressed Play and it works, .meta files committed, no Library/ / Temp/ / Logs/ / project files, no scene or prefab someone else is editing.
  • Bug report (label bug): what happened, what should have happened, steps, the first red Console line, branch or commit.
  • Feature idea (label idea): the idea, which part of the game, why it’s fun, who wants to build it.

Gotchas

Squash vs merge commits

CONTRIBUTING says the author clicks Squash and merge. The history on main shows ordinary merge commits (“Merge pull request #37 from gonzalezdan0315-sys/feature/xp-levels”), so in practice PRs are merged with Create a merge commit.

  • Unity scenes, prefabs and assets merge through merge=unityyamlmerge in .gitattributes; set up the driver once (Unity Setup).
  • A co-op change that alters messages or rules needs a NetSession.Protocol bump in the same PR (Add a Net Message).
  • Every PR that lands on main gets a row in History.
  • The sync task and the extra worktrees are local to Claudio’s PC: they are not in the repository, and other contributors have nothing like them.

Graph View

Backlinks