# GitHub Branch Protection And Review Rules

## Current Repository State

- Repository: `pacificao/AgrarianGameBuild`
- Visibility: private
- Default branch: `main`
- Current plan constraint: GitHub branch protection and repository rulesets are not enforceable on this private repository without GitHub Pro/Team or making the repository public.

GitHub API checks on 2026-05-15 returned the upgrade requirement for both branch protection and repository rulesets. To stay on the free tier, version 0.01 uses documented process controls and pull request templates now, with enforced protected `main` deferred to the later release/build pipeline milestone already tracked in the roadmap.

## Main Branch Policy

`main` is the only long-lived development branch for now.

Rules:

- Keep `main` buildable.
- Prefer short-lived task branches for risky, multi-file, Unreal asset, infrastructure, or parallel work.
- Direct commits to `main` are allowed only for small, scoped changes when validation is run and the working tree is understood.
- Do not commit secrets, raw terrain source datasets, generated builds, `DerivedDataCache`, `Intermediate`, `Saved`, `Binaries`, large source-art archives, or local machine caches.
- Before milestone demos or investor builds, confirm `main` is clean, pushed, and smoke-tested.

## Pull Request Rules

Use a pull request when any of these are true:

- The change touches gameplay systems, replication, persistence, build tooling, backup tooling, deployment, or server infrastructure.
- The change modifies Unreal binary assets that are hard to review in text.
- The change spans multiple roadmap items.
- The change could affect packaged builds, dedicated servers, map tile delivery, or player data.
- Another developer, workstation, or Codex session is working in the same area.

For PRs:

- Use the existing branch naming convention in `Docs/BranchingConventions.md`.
- Link the roadmap item being completed.
- Include validation steps actually run.
- Include screenshots or build artifacts only as links or paths, not committed binaries.
- Merge only after the change is reviewed or explicitly accepted by the project owner.

## Review Expectations

Minimum review expectations by change type:

| Change Type | Review Expectation |
| --- | --- |
| Docs-only | Self-review is acceptable if scoped and validated with `git diff --check`. |
| Small code-only fix | Self-review is acceptable when tests/build checks pass and risk is low. |
| Gameplay feature | Project owner review or second-developer review before merge when practical. |
| Unreal binary assets | Record the editor action taken and visual/build validation performed. |
| Build, backup, deployment, server, or GitHub workflow changes | Owner review before merge unless it is an emergency fix. |
| Secrets, credentials, auth, payment, wallet, or production data handling | Do not merge without explicit owner review. |

## Required Local Checks Before Push

Run the checks appropriate for the change:

- Documentation/text changes: `git diff --check`
- C++ changes: editor target build wrapper or Windows headless build command
- Packaged-client changes: packaged client build wrapper and smoke test
- Server changes: dedicated server build wrapper and relevant smoke test
- Backup/tooling changes: dry-run mode first when available

Record skipped checks in the PR or commit message.

## Free-Tier Controls Installed Now

- `Docs/Ops/GitHubBranchProtectionAndReviewRules.md` defines the working policy.
- `.github/PULL_REQUEST_TEMPLATE.md` gives a repeatable review checklist.
- The roadmap keeps paid/private branch protection enforcement in the later release/build pipeline section.

## Future Enforced Settings

When a paid GitHub plan is justified or the repository becomes public, enable protected `main` with:

- Require pull request before merge.
- Require at least one approving review for non-doc changes.
- Dismiss stale approvals when new commits are pushed.
- Require conversation resolution before merge.
- Require status checks once CI exists.
- Restrict force pushes.
- Restrict branch deletion.
- Require linear history if it does not interfere with Unreal asset workflows.
- Allow administrators to bypass only for emergency recovery.