| 1 | --- |
| 2 | name: gh-credit-harvest |
| 3 | description: "Harvest one community PR into a release branch with authorship and credit preserved, verified green, and a warm thank-you." |
| 4 | --- |
| 5 | |
| 6 | # gh-credit-harvest |
| 7 | |
| 8 | Harvest exactly one community PR into the real landing branch with full |
| 9 | authorship and machine-readable credit, verified green, then thank the |
| 10 | contributor. A PR is evidence: judge it from code, tests, comments, and checks, |
| 11 | never the title. Do not merge, close, tag, or publish without Hunter's approval — |
| 12 | this skill lands a credited commit and posts thanks; the workflow closes the PR. |
| 13 | |
| 14 | ## When to use |
| 15 | |
| 16 | - You have approval to land ONE specific community PR into a release branch. |
| 17 | - The PR is not yet on the landing branch (if it is, close-with-credit instead — see `gh-close-issues`). |
| 18 | - The landing branch may be local-only (e.g. `<release-branch>`); a main-based "mergeable" flag does not prove it lands cleanly. |
| 19 | |
| 20 | ## Workflow |
| 21 | |
| 22 | 1. Find the real landing branch (the one Hunter named, not always `main`) and fetch the PR head: |
| 23 | ```bash |
| 24 | git switch <release-branch> |
| 25 | git fetch origin pull/<N>/head |
| 26 | git log -1 --format='%H %an <%ae>' FETCH_HEAD # author to preserve |
| 27 | ``` |
| 28 | 2. Review from evidence, not the title. Read the diff, tests, linked issue, comments, and CI: |
| 29 | ```bash |
| 30 | gh pr view <N> --repo Hmbown/CodeWhale --json title,author,files,statusCheckRollup |
| 31 | gh pr diff <N> --repo Hmbown/CodeWhale |
| 32 | ``` |
| 33 | 3. Test mergeability against the REAL landing branch (local-only branches lie via the main flag): |
| 34 | ```bash |
| 35 | git merge-tree $(git merge-base HEAD FETCH_HEAD) HEAD FETCH_HEAD # empty/clean = no conflict |
| 36 | ``` |
| 37 | 4. Land it, preferring cherry-pick — it preserves the original author automatically: |
| 38 | ```bash |
| 39 | git cherry-pick <sha> # one or more commits from FETCH_HEAD |
| 40 | ``` |
| 41 | 5. If it conflicts, spans noise, or needs squashing, re-apply the narrow slice and commit with explicit author + credit trailers. Resolve `--author` and the co-author from `.github/AUTHOR_MAP` (fall back to numeric noreply): |
| 42 | ```bash |
| 43 | gh api users/<handle> --jq '"\(.id)+\(.login)@users.noreply.github.com"' |
| 44 | git commit --author="Name <ID+handle@users.noreply.github.com>" -m "fix(scope): what changed (#<N>)" \ |
| 45 | -m "Harvested from PR #<N> by @<handle>" \ |
| 46 | -m "Co-authored-by: Name <ID+handle@users.noreply.github.com>" |
| 47 | ``` |
| 48 | The `Harvested from PR #<N> by @<handle>` line in the body is what `.github/workflows/auto-close-harvested.yml` matches to auto-close with credit once the commit reaches `main`. |
| 49 | 6. Format and run the focused tests for the touched crate — only land green: |
| 50 | ```bash |
| 51 | cargo fmt --all |
| 52 | cargo test -p <crate> # the crate(s) the PR touched, not the whole workspace |
| 53 | python3 scripts/check-coauthor-trailers.py --author-map .github/AUTHOR_MAP --range HEAD~1..HEAD --check-authors |
| 54 | ``` |
| 55 | 7. Post a brief, warm, specific thank-you on the PR — name what the change fixed, no drama. Leave the PR open; the workflow closes it with credit when the commit lands on `main`: |
| 56 | ```bash |
| 57 | gh pr comment <N> --repo Hmbown/CodeWhale \ |
| 58 | --body "Thank you @<handle> — clean fix for <the specific bug>. Harvested into the v0.8.61 lane with your authorship preserved; it'll auto-close with credit once it reaches main." |
| 59 | ``` |
| 60 | |
| 61 | Grounded example: PR #3221 by @hongchen1993 (honour `DEEPSEEK_BASE_URL`/`DEEPSEEK_MODEL` in exec) cherry-picks cleanly, so its author is preserved with no manual trailers; a focused `cargo test -p` on the touched crate is enough to land it green. |
| 62 | |
| 63 | ## Red flags / don't |
| 64 | |
| 65 | - Don't judge or land from the title or labels alone — read code, tests, comments, and checks. |
| 66 | - Don't trust the GitHub main-based mergeable flag for a local-only release branch; prove it with `git merge-tree`. |
| 67 | - Don't squash away the original author. Cherry-pick when you can; only fall back to `--author` + trailers when you must. |
| 68 | - Don't invent co-author emails. Use `.github/AUTHOR_MAP`, then numeric noreply; never raw third-party, `.local`, placeholder, or bot emails. |
| 69 | - Don't omit the `Harvested from PR #<N> by @<handle>` body line — without it the PR won't auto-close with credit. |
| 70 | - Don't land red, harvest more than one PR per commit, or batch unrelated changes into the harvest. |
| 71 | - Don't merge, close, tag, publish, or push release artifacts without Hunter's approval. Keep the comment positive and crediting. |
| 72 | - Already on the landing branch? Don't re-harvest — close-with-credit via `gh-close-issues`. |
| 73 |