KMReader PR Workflow

Conventions for opening and merging PRs in this repo. Release-copy and version-cycle PRs follow ../appstore-release/SKILL.md instead.

Ground Rules

• All git-facing text is English: commits, PR titles and bodies, review comments.
• Conventional-commit titles with a scope: fix(reader): ..., feat(browse): ..., refactor(offline): ....
• All changes land via PR.
• A make bump commit rides inside the feature/fix PR — that is the normal delivery flow, not a separate PR. Skip it only when the user says so.
• Validate before opening: make format, then make build (all platforms). When localization keys changed, also make localize and fill translations per ../localization/SKILL.md.

Open a PR

1. Sync and branch:

git fetch origin
git switch -c <type>/<short-topic> origin/main

Name the branch after the title scope, e.g. fix/reader-end-page-cover.

2. Commit and git push -u origin <branch>. Intermediate commits may be work-in-progress; only the squash message lands on main.
3. Write the body to a file and create the PR with gh pr create --body-file; never pass a Markdown body inline:

cat > /tmp/kmreader-pr-body.md <<'EOF'
...
EOF
gh pr create --title "<conventional title>" --body-file /tmp/kmreader-pr-body.md

4. Body sections by change type:
   • fix: ## Problem (add ## Root cause when non-obvious) → ## Fix → ## Validation
   • feat / refactor: ## What → ## Why → ## Validation
   • Validation lists the commands actually run and their results (make build per platform, simulator or manual checks). There are no XCTest targets in this repo; state how behavior was verified.
   • End with Includes \make bump` to build NNN.` when a bump commit is included.
5. Link issues deliberately: Closes #N only when merging completes the whole issue; otherwise Part of #N.
6. Open ready for review; pass --draft only when the user asks. Report the PR URL.

Merge a PR

1. Gate on green CI and a clean merge state:

gh pr checks <N>
gh pr view <N> --json mergeable,mergeStateStatus

iOS / macOS / tvOS checks must all pass and the state must be CLEAN. When checks are red, fix and push again; merge red only on explicit user instruction.

2. Squash merge with a freshly composed message — never the auto-generated commit list. Write the body as a self-contained summary of the merged change: what user-visible behavior changed and why, plus side effects worth knowing later (removed localization keys, migrations, follow-ups). ../changelog/SKILL.md generates App Store notes from main's commit bodies (%s + %b between the latest tag and HEAD), so this message is the changelog source material: behavior first, file/class names only when they aid understanding. The PR discussion stays on GitHub; the commit must stand alone.
3. Merge and clean up. Like PR creation, the body goes through a file — never inline a Markdown body into --body:

cat > /tmp/kmreader-merge-body.md <<'EOF'
<summary from step 2>
EOF
gh pr merge <N> --squash --delete-branch \
  --subject "<conventional title> (#N)" \
  --body-file /tmp/kmreader-merge-body.md

git fetch --prune origin
git switch main
git pull --ff-only origin main

4. Done when: main contains the squash commit with the new message, and both remote and local feature branches are gone.