Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

enhancement: scan release notes for shared contributor credit (#5433)

Jeremiah Lowinf2b965bf73ea
diff --git a/.agents/skills/fix-issue/SKILL.md b/.agents/skills/fix-issue/SKILL.md
index 1d33cbebf..ba33d334d 100644
--- a/.agents/skills/fix-issue/SKILL.md
+++ b/.agents/skills/fix-issue/SKILL.md
@@ -25,4 +25,6 @@ Within existing authorization, update the existing PR or open a focused one, usi
For a maintainer implementation of a community issue, apply [Contributor credit](../../../docs/development/contributing.mdx#contributor-credit) before committing and publishing. Read the issue author's GitHub profile to establish their account identity; prefer the GitHub-provided noreply address, and ask if identity is unclear. Add their `Co-authored-by: Name <email>` trailer to the implementation commit and at the end of the PR description, alongside existing contributor attribution. Reporting the problem is enough; do not require code or root-cause analysis. Honor opt-outs and do not credit bot accounts as human issue contributors.
+Maintainers are generally exempt from supplemental credit checks. For maintainer reports and routine backports, preserve existing community attribution and proceed; do not add a maintainer merely because they opened the original PR or ask for guidance on that basis. A backport does not need a fresh credit audit.
+
Start [review-pr](../review-pr/SKILL.md) monitoring after publication. CI completion and review completion are distinct. Resolve real findings and report material compatibility decisions; a green check does not settle them. Do not merge or mark ready without authorization.
diff --git a/.agents/skills/release/SKILL.md b/.agents/skills/release/SKILL.md
index c0608f7b1..562a4456d 100644
--- a/.agents/skills/release/SKILL.md
+++ b/.agents/skills/release/SKILL.md
@@ -22,19 +22,51 @@ one gets a follow-up patch, never a re-tag.
```bash
git fetch origin && git log v<prev>..origin/<branch> --format='%h %s'
gh api -X POST repos/PrefectHQ/fastmcp/releases/generate-notes \
- -f tag_name=v<new> -f target_commitish=<branch> -f previous_tag_name=v<prev> --jq .body
+ -f tag_name=v<new> -f target_commitish=<branch> -f previous_tag_name=v<prev> --jq .body \
+ > /tmp/generated-notes.md
+ uv run scripts/release_contributor_credit.py /tmp/generated-notes.md \
+ > /tmp/contributor-credit.json
```
Read the two most recent releases for voice: `gh release list -L 5`, then
`gh release view <tag>` on each.
- **Verify contributor credit in the release preview.** Attribution is recorded
- during PR preparation and verified at merge; do not repeat that audit for every
- PR and issue. Use the existing release inventory and a batch read of merged
- commit co-author metadata to supplement generated notes with credited reporters
- alongside PR authors. Inspect an individual PR or issue only to resolve a
- discrepancy. Check prior contribution history only for people being newly added
- to `New Contributors`; earlier credited issue implementations count too.
+ **Review the scan's attribution candidates.** The helper batch-fetches metadata
+ only for PRs in the generated notes. It suggests shared credit for human authors
+ of the PR commits and final merged commit, plus issue reporters whose issues
+ are closed by a maintainer PR, even when their co-author trailer is missing. Human co-authors
+ are included even when the PR has no linked issue. It excludes known
+ agent identities and bots; a GitHub `User` identity alone does not prove someone
+ is human. Maintainer permission checks are reused across PRs.
+
+ Supplemental attribution is for community contributors. Keep the PR author's
+ credit and any credit already present, but do not add other maintainers or
+ investigate their first-time status. Routine maintainer backports need no fresh
+ attribution audit and no request for guidance. Preserve existing community credit.
+
+ Apply the suggested entries to `/tmp/generated-notes.md`, for example
+ `Fix issue #123 by @jlowin and @reporter in <PR URL>`. Check the flagged exceptions:
+ unknown commit identities, missing reporter co-authorship, and issue closures
+ that do not represent a contribution (such as administrative duplicate closure).
+ Inspect individual PRs or issues only to resolve these discrepancies, rather than
+ re-reading every PR. The helper is read-only; it does not change notes or decide
+ who is a new contributor. Check prior contribution history only for people
+ listed in `first_time_review`: added contributors and GitHub's first-time
+ candidates. Earlier co-authorship and credited issue implementations count too.
+ Add verified first-time contributors to `New Contributors` with the resolving
+ PR link, and keep returning contributors in the shared change entries.
+
+ **Update both contributor counts after attribution is complete.** Count distinct
+ human GitHub accounts across the release entries for the total contributor count,
+ and distinct accounts in the final `New Contributors` list for the first-time
+ count. Count each person once across multiple PRs or roles, and exclude agents
+ and bots. The helper's `total_contributors` is the proposed total; its
+ `generated_first_time_count` is only the original baseline, not the final count.
+ Resolve unknown identities and opt-outs before finalizing totals. Include the
+ final counts in the release introduction (for example, `Thanks to our 12
+ contributors, including 3 first-time contributors.`), and update any other
+ contributor totals in the notes to agree. These counts and shared attribution
+ must appear in both the GitHub release and the docs changelog.
Follow [Contributor credit](../../../docs/development/contributing.mdx#contributor-credit),
honor opt-outs, and deduplicate entries. Save the completed generated notes to
`/tmp/generated-notes.md`.
diff --git a/.agents/skills/review-pr/SKILL.md b/.agents/skills/review-pr/SKILL.md
index 1ab96d059..5f5af7cb9 100644
--- a/.agents/skills/review-pr/SKILL.md
+++ b/.agents/skills/review-pr/SKILL.md
@@ -36,7 +36,7 @@ Read review threads and author replies, not just summary verdicts. Codex can upd
Preserve draft status unless the user authorizes changing it. Approval, publication, and merging remain subject to AGENTS.md and existing authorization. Immediately before an authorized merge, recheck the title, body, labels, head, checks, and branch protections; obey all draft and DNM stops.
-For maintainer implementations of community issues, check [Contributor credit](../../../docs/development/contributing.mdx#contributor-credit) as part of readiness: the issue author's verified co-author trailer must be in the implementation commit and PR description. Missing attribution is unfinished PR preparation. In review-only work, report the omission rather than editing the PR.
+For maintainer implementations of community issues, check [Contributor credit](../../../docs/development/contributing.mdx#contributor-credit) as part of readiness: the issue author's verified co-author trailer must be in the implementation commit and PR description. Missing community attribution is unfinished PR preparation. Maintainers are generally exempt: do not flag missing credit for another maintainer or ask for guidance about it. Routine backports preserve existing community attribution without a fresh credit audit. In review-only work, report an applicable omission rather than editing the PR.
Preserve attribution through whichever merge strategy is chosen. For a squash merge, write the exact final commit body to a temporary file, including the issue link and all human co-author trailers from the PR description and commits. Inspect it and pass it explicitly with `gh pr merge <number> --squash --body-file /tmp/merge-body.md --match-head-commit <reviewed-head>`, adding any already-authorized merge flags. Do not rely on GitHub's default squash message. For merge or rebase, verify the attributed commits will be retained. After merging, inspect the landed commit(s) and confirm the co-authors are present. These steps do not authorize a merge or prescribe its strategy.
diff --git a/AGENTS.md b/AGENTS.md
index 05b9e1cac..341219ec8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -111,6 +111,7 @@ Load the `release` skill to cut one; it holds the procedure. The policy it imple
### Commit Messages and Agent Attribution
+- **Keep contributor credit focused on the community.** Maintainers are generally exempt from supplemental attribution checks. Do not add another maintainer merely for reporting, reviewing, opening the original PR, or handling a backport, and do not ask for guidance about those cases. Routine backports preserve existing community credit; they do not require a fresh attribution audit. Preserve attribution already present and proceed with the work.
- **Credit issue authors as contributors.** When acting for a maintainer and implementing a community bug report, enhancement request, or documentation issue, give the issue author co-authorship of the resulting change. Follow [Contributor credit](docs/development/contributing.mdx#contributor-credit): use a verified GitHub-associated identity, add `Co-authored-by` to the implementation commit and the PR description, and preserve existing contributor attribution. This is a required part of preparing the PR, not an optional thank-you or something the reporter must request.
- **Preserve credit through any merge strategy.** Before an authorized merge, verify the resulting commit will retain the co-author trailers. Squash merges are common here: explicitly supply a commit message containing the trailers rather than relying on GitHub's default squash message. This does not require choosing squash. Verify the landed commit after merging.
- **Carry contributor credit into releases.** Include credited issue authors alongside PR authors in release entries and include first-time contributors under `New Contributors`. GitHub's generated notes are a starting point; check and supplement them using the release skill. The same completed notes must feed the GitHub release and docs changelog.
diff --git a/docs/development/contributing.mdx b/docs/development/contributing.mdx
index e995c0e27..31c1eee01 100644
--- a/docs/development/contributing.mdx
+++ b/docs/development/contributing.mdx
@@ -28,6 +28,8 @@ Do not post comments just to claim an issue or ask to be assigned. A concise rep
### Contributor credit
+This policy recognizes community contributions. Maintainers are generally exempt from supplemental credit checks: reporting, reviewing, or backporting another maintainer's change does not require adding them as a contributor. Routine backports preserve existing community attribution without repeating the credit review.
+
If your issue leads to a merged change implemented by a maintainer, we credit you as a contributor to that change. This applies to bug reports, enhancement requests, and documentation issues. You do not need to write code, diagnose the root cause, or propose an implementation: identifying the problem or explaining the use case is a contribution.
Credit includes co-authorship of the merged commit and attribution alongside the PR author in the release notes. If this is your first contribution to FastMCP, you are included under **New Contributors** in the release that first includes the change. Maintainers and agents working on their behalf handle this as part of preparing, merging, and releasing the PR. Opening an issue does not guarantee that it will be implemented.
diff --git a/scripts/release_contributor_credit.py b/scripts/release_contributor_credit.py
new file mode 100644
index 000000000..d71b09973
--- /dev/null
+++ b/scripts/release_contributor_credit.py
@@ -0,0 +1,297 @@
+"""Scan generated release notes for shared human contributor credit.
+
+Usage: uv run scripts/release_contributor_credit.py /tmp/generated-notes.md
+
+Prints attribution candidates as JSON. Reads GitHub metadata without modifying
+PRs, issues, commits, or release notes. New-contributor history and opt-outs are
+reviewed by the release agent only for the candidates returned here.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+from pathlib import Path
+from typing import Any
+
+REPO = "PrefectHQ/fastmcp"
+AGENT_LOGINS = {"claude", "codex", "copilot", "github-copilot", "openai-codex", "devin"}
+AGENT_NAMES = re.compile(
+ r"^(?:claude (?:opus|sonnet|haiku)|codex|openai codex|github copilot|copilot|devin)(?:\b|$)",
+ re.I,
+)
+HANDLE = r"@[\w-]+(?:\[bot\])?"
+PR_ENTRY = re.compile(
+ rf"^(?P<prefix>\* .+) by (?P<authors>{HANDLE}(?:, (?:and )?{HANDLE}| and {HANDLE})*) in "
+ r"https://github\.com/" + re.escape(REPO) + r"/pull/(?P<number>\d+)\s*$",
+ re.M,
+)
+
+
+def api(*args: str) -> dict[str, Any]:
+ result = json.loads(subprocess.check_output(["gh", "api", *args], text=True))
+ if result.get("errors"):
+ raise ValueError(f"GitHub query failed: {result['errors']}")
+ return result
+
+
+def is_human(actor: dict[str, Any] | None) -> bool:
+ if not actor:
+ return False
+ login = actor["login"].lower()
+ return (
+ actor.get("__typename") != "Bot"
+ and not login.endswith("[bot]")
+ and login not in AGENT_LOGINS
+ )
+
+
+def is_agent_author(author: dict[str, Any]) -> bool:
+ user = author.get("user")
+ return (
+ bool(user and not is_human(user))
+ or bool(AGENT_NAMES.match(author["name"]))
+ or author["email"].lower() in {"[email protected]", "[email protected]"}
+ )
+
+
+def fetch_prs(numbers: list[int]) -> dict[int, dict[str, Any]]:
+ prs: dict[int, dict[str, Any]] = {}
+ for start in range(0, len(numbers), 30):
+ fields = "\n".join(
+ f"""p{number}: pullRequest(number:{number}) {{
+ number author {{ login __typename }}
+ closingIssuesReferences(first:100) {{
+ nodes {{ number url author {{ login __typename }} }}
+ pageInfo {{ hasNextPage }}
+ }}
+ commits(first:100) {{
+ nodes {{ commit {{ authors(first:100) {{
+ nodes {{ name email user {{ login __typename }} }}
+ pageInfo {{ hasNextPage }}
+ }} }} }}
+ pageInfo {{ hasNextPage }}
+ }}
+ mergeCommit {{ authors(first:100) {{
+ nodes {{ name email user {{ login __typename }} }}
+ pageInfo {{ hasNextPage }}
+ }} }}
+ }}"""
+ for number in numbers[start : start + 30]
+ )
+ query = (
+ 'query { repository(owner:"PrefectHQ",name:"fastmcp") {' + fields + "} }"
+ )
+ result = api("graphql", "-f", f"query={query}")
+ for pr in result["data"]["repository"].values():
+ if pr is None or pr["mergeCommit"] is None:
+ raise ValueError("Release notes reference a missing or unmerged PR")
+ if any(
+ connection["pageInfo"]["hasNextPage"]
+ for connection in (
+ pr["closingIssuesReferences"],
+ pr["mergeCommit"]["authors"],
+ pr["commits"],
+ *(node["commit"]["authors"] for node in pr["commits"]["nodes"]),
+ )
+ ):
+ raise ValueError(
+ f"PR #{pr['number']}: attribution metadata is truncated"
+ )
+ prs[pr["number"]] = pr
+ return prs
+
+
+def release_prs(notes: str) -> dict[int, dict[str, Any]]:
+ entries = list(PR_ENTRY.finditer(notes))
+ # Fail visibly if the generated format changes; a silent empty scan loses credit.
+ linked = set(
+ re.findall(r"https://github\.com/" + re.escape(REPO) + r"/pull/(\d+)", notes)
+ )
+ parsed = {entry["number"] for entry in entries}
+ if linked - parsed:
+ raise ValueError(
+ f"Cannot parse release entries for PRs: {sorted(linked - parsed)}"
+ )
+ return fetch_prs(sorted(int(number) for number in parsed))
+
+
+def commit_authors(pr: dict[str, Any]) -> list[dict[str, Any]]:
+ return [
+ author
+ for node in pr["commits"]["nodes"]
+ for author in node["commit"]["authors"]["nodes"]
+ ] + pr["mergeCommit"]["authors"]["nodes"]
+
+
+def note_actors(prs: dict[int, dict[str, Any]]) -> dict[str, dict[str, Any]]:
+ """Keep GitHub actor types, including plain-handle aliases for app bots."""
+ actors = {}
+ for pr in prs.values():
+ sources = [pr["author"]]
+ sources.extend(
+ issue["author"] for issue in pr["closingIssuesReferences"]["nodes"]
+ )
+ sources.extend(author.get("user") for author in commit_authors(pr))
+ for actor in sources:
+ if actor:
+ key = actor["login"].lower()
+ actors[key] = actor
+ if key.endswith("[bot]"):
+ actors[key.removesuffix("[bot]")] = actor
+ return actors
+
+
+def scan_notes(
+ notes: str, prs: dict[int, dict[str, Any]] | None = None
+) -> list[dict[str, Any]]:
+ if prs is None:
+ prs = release_prs(notes)
+ actors = note_actors(prs)
+ entries = list(PR_ENTRY.finditer(notes))
+ permissions: dict[str, bool] = {}
+
+ def is_maintainer(login: str) -> bool:
+ key = login.lower()
+ if key not in permissions:
+ permission = api(f"repos/{REPO}/collaborators/{login}/permission")[
+ "permission"
+ ]
+ permissions[key] = permission in {"admin", "maintain", "write"}
+ return permissions[key]
+
+ candidates = []
+ for entry in entries:
+ number = int(entry["number"])
+ pr = prs[number]
+ authors = commit_authors(pr)
+ humans = [author for author in authors if not is_agent_author(author)]
+ original_credit = {
+ mention.lstrip("@").lower(): mention.lstrip("@")
+ for mention in re.findall(HANDLE, entry["authors"])
+ if is_human(actors.get(mention.lstrip("@").lower()))
+ }
+ credited = dict(original_credit)
+ if is_human(pr["author"]):
+ login = pr["author"]["login"]
+ credited[login.lower()] = login
+ for author in humans:
+ if is_human(author.get("user")):
+ login = author["user"]["login"]
+ if login.lower() not in credited and not is_maintainer(login):
+ credited[login.lower()] = login
+ issues = [
+ issue
+ for issue in pr["closingIssuesReferences"]["nodes"]
+ if is_human(issue["author"])
+ ]
+ missing_reporters = []
+ extra_reporters = [
+ issue
+ for issue in issues
+ if issue["author"]["login"].lower() not in credited
+ ]
+ if extra_reporters and pr["author"]:
+ login = pr["author"]["login"]
+ if is_maintainer(login):
+ for issue in extra_reporters:
+ reporter = issue["author"]["login"]
+ if reporter.lower() not in credited and not is_maintainer(reporter):
+ credited[reporter.lower()] = reporter
+ missing_reporters.append(reporter)
+ unmapped = list(
+ dict.fromkeys(author["name"] for author in humans if not author.get("user"))
+ )
+ if (
+ set(credited) == set(original_credit)
+ and not missing_reporters
+ and not unmapped
+ ):
+ continue
+ handles = [f"@{login}" for login in credited.values()]
+ shared = (
+ " and ".join(handles)
+ if len(handles) <= 2
+ else ", ".join(handles[:-1]) + ", and " + handles[-1]
+ )
+ candidates.append(
+ {
+ "pr": number,
+ "credit": list(credited.values()),
+ "closing_issues": [
+ {
+ "number": issue["number"],
+ "url": issue["url"],
+ "author": issue["author"]["login"],
+ }
+ for issue in issues
+ ],
+ "missing_reporter_coauthors": missing_reporters,
+ "unmapped_commit_authors": unmapped,
+ "suggested_entry": (
+ f"{entry['prefix']} by {shared} in https://github.com/{REPO}/pull/{number}"
+ if handles
+ else None
+ ),
+ }
+ )
+ return candidates
+
+
+def main() -> None:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("notes", type=Path)
+ args = parser.parse_args()
+ notes = args.notes.read_text()
+ prs = release_prs(notes)
+ candidates = scan_notes(notes, prs)
+ print(json.dumps(summarize_credit(notes, candidates, prs), indent=2))
+
+
+def summarize_credit(
+ notes: str, candidates: list[dict[str, Any]], prs: dict[int, dict[str, Any]]
+) -> dict[str, Any]:
+ """Count unique human contributors and identify first-time history checks.
+
+ GitHub's first-time candidates and supplemental contributors need a history
+ check, including prior co-authorship, before finalizing that list and its count.
+ """
+ actors = note_actors(prs)
+ original: dict[str, str] = {}
+ for entry in PR_ENTRY.finditer(notes):
+ for mention in re.findall(HANDLE, entry["authors"]):
+ login = mention.lstrip("@")
+ if is_human(actors.get(login.lower())):
+ original[login.lower()] = login
+ credited = dict(original)
+ for candidate in candidates:
+ for login in candidate["credit"]:
+ credited.setdefault(login.lower(), login)
+ first_time: dict[str, str] = {}
+ for login in re.findall(
+ rf"^\* ({HANDLE}) made their first contribution in ", notes, re.M
+ ):
+ login = login.lstrip("@")
+ if is_human(actors.get(login.lower())):
+ first_time[login.lower()] = login
+ return {
+ "candidates": candidates,
+ "contributors": sorted(credited.values(), key=str.lower),
+ "total_contributors": len(credited),
+ "generated_first_time_contributors": sorted(first_time.values(), key=str.lower),
+ "generated_first_time_count": len(first_time),
+ "first_time_review": sorted(
+ (
+ login
+ for key, login in credited.items()
+ if key not in original or key in first_time
+ ),
+ key=str.lower,
+ ),
+ }
+
+
+if __name__ == "__main__":
+ main()
diff --git a/tests/scripts/test_release_contributor_credit.py b/tests/scripts/test_release_contributor_credit.py
new file mode 100644
index 000000000..545356cf9
--- /dev/null
+++ b/tests/scripts/test_release_contributor_credit.py
@@ -0,0 +1,301 @@
+import json
+from typing import Any
+
+import pytest
+
+from scripts.release_contributor_credit import fetch_prs, scan_notes, summarize_credit
+
+
+def actor(login: str, kind: str = "User") -> dict[str, str]:
+ return {"login": login, "__typename": kind}
+
+
+def pr_metadata(
+ number: int,
+ author: str = "maintainer",
+ coauthors: tuple[str, ...] = (),
+ reporters: tuple[str, ...] = (),
+) -> dict[str, Any]:
+ return {
+ "number": number,
+ "author": actor(author),
+ "closingIssuesReferences": {
+ "nodes": [
+ {
+ "number": i,
+ "url": f"https://github.com/PrefectHQ/fastmcp/issues/{i}",
+ "author": actor(login),
+ }
+ for i, login in enumerate(reporters, 1)
+ ],
+ "pageInfo": {"hasNextPage": False},
+ },
+ "commits": {"nodes": [], "pageInfo": {"hasNextPage": False}},
+ "mergeCommit": {
+ "authors": {
+ "nodes": [
+ {
+ "name": login,
+ "email": f"{login}@users.noreply.github.com",
+ "user": actor(login),
+ }
+ for login in (author, *coauthors)
+ ],
+ "pageInfo": {"hasNextPage": False},
+ }
+ },
+ }
+
+
+def entry(number: int, author: str = "maintainer") -> str:
+ return f"* Fix lookup by @{author} in https://github.com/PrefectHQ/fastmcp/pull/{number}\n"
+
+
+def mock_github(
+ monkeypatch: pytest.MonkeyPatch,
+ prs: list[dict[str, Any]],
+ permission: str = "write",
+ maintainers: tuple[str, ...] = ("maintainer",),
+) -> list[list[str]]:
+ calls: list[list[str]] = []
+
+ def respond(command: list[str], **kwargs: Any) -> str:
+ calls.append(command)
+ if command[2] == "graphql":
+ return json.dumps(
+ {"data": {"repository": {f"p{pr['number']}": pr for pr in prs}}}
+ )
+ assert command[2].endswith("/permission")
+ login = command[2].split("/")[-2]
+ return json.dumps(
+ {"permission": permission if login in maintainers else "read"}
+ )
+
+ monkeypatch.setattr(
+ "scripts.release_contributor_credit.subprocess.check_output", respond
+ )
+ return calls
+
+
+def test_batch_credits_missing_reporters_and_reuses_maintainer_permission(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ calls = mock_github(
+ monkeypatch,
+ [
+ pr_metadata(1, reporters=("reporter",)),
+ pr_metadata(2, reporters=("reporter",)),
+ ],
+ )
+ result = scan_notes(entry(1) + entry(2))
+ assert [candidate["credit"] for candidate in result] == [
+ ["maintainer", "reporter"],
+ ["maintainer", "reporter"],
+ ]
+ assert result[0]["missing_reporter_coauthors"] == ["reporter"]
+ assert "by @maintainer and @reporter in" in result[0]["suggested_entry"]
+ assert len(calls) == 3 # Metadata and one permission lookup per distinct account.
+
+
+def test_human_coauthors_survive_agent_filter_without_an_issue(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ pr = pr_metadata(1, coauthors=("helper", "claude", "codex", "automation[bot]"))
+ pr["mergeCommit"]["authors"]["nodes"].append(
+ {"name": "Claude Opus 5.5", "email": "[email protected]", "user": None}
+ )
+ calls = mock_github(monkeypatch, [pr])
+ result = scan_notes(entry(1))
+ assert result[0]["credit"] == ["maintainer", "helper"]
+ assert result[0]["unmapped_commit_authors"] == []
+ assert len(calls) == 2
+
+
+def test_external_pr_does_not_automatically_credit_distinct_issue_author(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ mock_github(
+ monkeypatch,
+ [pr_metadata(1, author="contributor", reporters=("reporter",))],
+ permission="read",
+ )
+ assert scan_notes(entry(1, "contributor")) == []
+
+
+def test_deduplicates_reporters_and_renders_oxford_comma(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ mock_github(
+ monkeypatch,
+ [
+ pr_metadata(
+ 1, coauthors=("helper",), reporters=("helper", "reporter", "reporter")
+ )
+ ],
+ )
+ result = scan_notes(entry(1))
+ assert result[0]["credit"] == ["maintainer", "helper", "reporter"]
+ assert "by @maintainer, @helper, and @reporter in" in result[0]["suggested_entry"]
+
+
+def test_unmapped_human_author_is_flagged_without_guessing_a_handle(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ pr = pr_metadata(1)
+ pr["mergeCommit"]["authors"]["nodes"].append(
+ {"name": "Helpful Person", "email": "[email protected]", "user": None}
+ )
+ mock_github(monkeypatch, [pr])
+ result = scan_notes(entry(1))
+ assert result[0]["unmapped_commit_authors"] == ["Helpful Person"]
+ assert result[0]["credit"] == ["maintainer"]
+
+
+def test_changed_notes_format_fails_visibly(monkeypatch: pytest.MonkeyPatch) -> None:
+ calls = mock_github(monkeypatch, [])
+ with pytest.raises(ValueError, match="Cannot parse release entries"):
+ scan_notes("* Fix lookup (https://github.com/PrefectHQ/fastmcp/pull/1)")
+ assert calls == []
+
+
[email protected]("connection", ["issues", "authors"])
+def test_truncated_metadata_fails_visibly(
+ monkeypatch: pytest.MonkeyPatch, connection: str
+) -> None:
+ pr = pr_metadata(1)
+ nodes = (
+ pr["closingIssuesReferences"]
+ if connection == "issues"
+ else pr["mergeCommit"]["authors"]
+ )
+ nodes["pageInfo"]["hasNextPage"] = True
+ mock_github(monkeypatch, [pr])
+ with pytest.raises(ValueError, match="truncated"):
+ fetch_prs([1])
+
+
+def test_bot_authored_generated_entry_is_parsed_without_crediting_bot(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ mock_github(monkeypatch, [pr_metadata(1, author="dependabot[bot]")])
+ assert scan_notes(entry(1, "dependabot[bot]")) == []
+
+
+def test_single_human_coauthor_of_bot_pr_is_credited(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ mock_github(
+ monkeypatch, [pr_metadata(1, author="automation[bot]", coauthors=("helper",))]
+ )
+ result = scan_notes(entry(1, "automation[bot]"))
+ assert result[0]["credit"] == ["helper"]
+ assert "by @helper in" in result[0]["suggested_entry"]
+
+
+def test_summary_counts_unique_humans_and_flags_first_time_candidates() -> None:
+ notes = (
+ entry(1)
+ + entry(2)
+ + entry(3, "dependabot[bot]")
+ + "\n## New Contributors\n"
+ + "* @maintainer made their first contribution in https://github.com/PrefectHQ/fastmcp/pull/1\n"
+ + "* @claude made their first contribution in https://github.com/PrefectHQ/fastmcp/pull/2\n"
+ )
+ candidates = [
+ {"credit": ["maintainer", "reporter"]},
+ {"credit": ["Maintainer", "reporter", "helper"]},
+ ]
+ prs = {
+ 1: pr_metadata(1, reporters=("reporter",)),
+ 2: pr_metadata(2, coauthors=("helper", "claude")),
+ 3: pr_metadata(3, author="dependabot[bot]"),
+ }
+ result = summarize_credit(notes, candidates, prs)
+ assert result["contributors"] == ["helper", "maintainer", "reporter"]
+ assert result["total_contributors"] == 3
+ assert result["generated_first_time_contributors"] == ["maintainer"]
+ assert result["generated_first_time_count"] == 1
+ assert result["first_time_review"] == ["helper", "maintainer", "reporter"]
+
+
+def test_maintainer_report_and_coauthor_need_no_supplemental_credit(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ mock_github(
+ monkeypatch,
+ [
+ pr_metadata(
+ 1, coauthors=("othermaintainer",), reporters=("othermaintainer",)
+ )
+ ],
+ maintainers=("maintainer", "othermaintainer"),
+ )
+ assert scan_notes(entry(1)) == []
+
+
+def test_existing_maintainer_credit_is_preserved(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ calls = mock_github(
+ monkeypatch,
+ [pr_metadata(1, coauthors=("othermaintainer",))],
+ maintainers=("maintainer", "othermaintainer"),
+ )
+ notes = entry(1).replace(
+ "by @maintainer in", "by @maintainer and @othermaintainer in"
+ )
+ assert scan_notes(notes) == []
+ assert len(calls) == 1
+
+
[email protected]("merge_strategy", ["merge", "rebase", "squash"])
+def test_credits_authors_from_earlier_pr_commits(
+ monkeypatch: pytest.MonkeyPatch, merge_strategy: str
+) -> None:
+ pr = pr_metadata(1)
+ earlier = pr_metadata(1, author="helper", coauthors=("reporter", "claude"))
+ pr["commits"]["nodes"] = [{"commit": earlier["mergeCommit"]}]
+ if merge_strategy == "squash":
+ pr["mergeCommit"] = pr_metadata(1, coauthors=("helper", "reporter"))[
+ "mergeCommit"
+ ]
+ calls = mock_github(monkeypatch, [pr])
+ result = scan_notes(entry(1))
+ assert "commits(first:100)" in calls[0][-1]
+ assert result[0]["credit"] == ["maintainer", "helper", "reporter"]
+
+
[email protected]("nested", [False, True])
+def test_truncated_pr_commit_metadata_fails_visibly(
+ monkeypatch: pytest.MonkeyPatch, nested: bool
+) -> None:
+ pr = pr_metadata(1)
+ earlier = pr_metadata(1, author="helper")
+ pr["commits"]["nodes"] = [{"commit": earlier["mergeCommit"]}]
+ connection = earlier["mergeCommit"]["authors"] if nested else pr["commits"]
+ connection["pageInfo"]["hasNextPage"] = True
+ mock_github(monkeypatch, [pr])
+ with pytest.raises(ValueError, match="truncated"):
+ fetch_prs([1])
+
+
[email protected]("login", ["dependabot", "prefect-renovate"])
+def test_plain_app_handles_are_excluded_from_all_counts(
+ monkeypatch: pytest.MonkeyPatch, login: str
+) -> None:
+ pr = pr_metadata(1, author=f"{login}[bot]")
+ pr["author"] = actor(f"{login}[bot]", "Bot")
+ pr["mergeCommit"]["authors"]["nodes"][0]["user"] = pr["author"]
+ notes = (
+ entry(1, login)
+ + f"* @{login} made their first contribution in https://github.com/PrefectHQ/fastmcp/pull/1\n"
+ )
+ calls = mock_github(monkeypatch, [pr])
+ prs = fetch_prs([1])
+ candidates = scan_notes(notes, prs)
+ result = summarize_credit(notes, candidates, prs)
+ assert result["contributors"] == []
+ assert result["total_contributors"] == 0
+ assert result["generated_first_time_count"] == 0
+ assert result["first_time_review"] == []
+ assert len(calls) == 1