Upstream Audit

Context

![ -f pyproject.toml ] && grep '^name' pyproject.toml | head -1 || echo "No pyproject.toml" !git config user.name 2>/dev/null || echo "No git user" !gh api /user --jq '.login' 2>/dev/null || echo "No gh auth" ![ -f docs/upstream.md ] && grep '^## ' docs/upstream.md || echo "No docs/upstream.md yet" ![ -f docs/upstream.md ] && grep -c 'github.com/' docs/upstream.md || echo 0

Instructions

You create and maintain docs/upstream.md, which tracks the project's relationship with its upstream dependencies: code contributed back, workarounds provided, issues reported, and features declined.

Reference example

Fetch this file as reference when building or auditing an upstream page:

• kdeldycke/click-extra/docs/upstream.md: tracks merged PRs across Click, python-tabulate, Pygments, Furo, Cloup, and click-contrib projects, plus upstreamed workarounds, feature-area-grouped workarounds still in place, declined PRs, and open upstream issues.

Document structure

The page uses five sections:

1. Code contributed upstream - PRs authored by the maintainer and merged into upstream projects. Organized by project, optionally grouped by theme within large projects.
2. Upstreamed from this project - Issues the project solved with local workarounds first, then the fix was contributed upstream and the workaround removed locally.
3. Addressed by this project - Issues that remain open or unfixed upstream; this project provides the solution. Grouped by feature area.
4. Declined by upstream - PRs or issues rejected by upstream maintainers; this project provides the functionality regardless.
5. Open upstream - PRs and issues still pending upstream.

Items are listed as markdown links: - [`#N` - Title](url)

Scope selection

• audit (default): Check status of all linked issues/PRs in an existing page and report items that need to move between sections.
• init: Create docs/upstream.md from scratch by discovering all upstream contributions.
• refresh: Same as audit, but also apply the changes.
• sync-git: Scan the git log for upstream references not yet in the document.

Creating from scratch (init)

1. Identify the maintainer

Determine the GitHub username from gh api /user --jq '.login' or git config user.name. Confirm with the user.

2. Identify upstream dependencies

Extract dependencies from pyproject.toml (both [project.dependencies] and [project.optional-dependencies]/[dependency-groups]). For each dependency, find its GitHub repository:

• Check PyPI metadata: pip show <pkg> or https://pypi.org/pypi/<pkg>/json
• Check uv.lock for source URLs

Also include significant build/test/docs dependencies (Sphinx themes, pytest plugins, linters) that the project interacts with.

3. Discover contributions

For each upstream repo, search for the maintainer's participation:

gh api "repos/{owner}/{repo}/issues?creator={username}&state=all&per_page=100" \
  --jq '.[] | "#\(.number) \(.title) [\(.state)] \(.pull_request // empty | "PR") \(.html_url)"'

For repos with many results, also check PRs specifically:

gh search prs --author {username} --repo {owner}/{repo} --limit 50

For a maintainer active across many projects, sweep globally first and filter by repo afterwards: one search over everything they authored beats guessing the repo list, and surfaces upstreams nobody remembered.

gh search prs --author {username} --limit 1000 --json repository,number,title,state,url -- -user:{username}
gh search issues --author {username} --limit 1000 --json repository,number,title,state,url -- -user:{username}

Three traps in that sweep:

• The raw qualifier excluding their own repos (-user:{username}) must come after the -- separator, and every flag before it: anything after -- is read as a search term.
• Results are best-match, so a --limit below the true total drops the oldest items silently. Treat a result count equal to the limit as truncated.
• A URL cited in the codebase is not a contribution: authorship from these sweeps separates "we filed it" from "we cite someone else's issue as evidence". Both matter, but they land in different sections.

When the maintainer runs several projects with upstream pages, dedupe against the sibling pages and give each item one canonical home: the project whose code consumes the dependency. Distribution packaging of the project itself belongs to its packaging docs, not this page.

4. Check status of each item

For PRs: gh pr view <url> --json state,mergedAt,title For issues: gh issue view <url> --json state,stateReason,title

To resolve many items at once, batch them into a single GraphQL call with aliased issueOrPullRequest nodes:

gh api graphql -F query=@states.graphql

query {
  a1: repository(owner: "{owner}", name: "{repo}") { issueOrPullRequest(number: 123) { ...S } }
  a2: repository(owner: "{owner}", name: "{repo}") { issueOrPullRequest(number: 456) { ...S } }
}
fragment S on IssueOrPullRequest {
  ... on Issue { state stateReason title }
  ... on PullRequest { state merged title }
}

stateReason separates a completed issue from one closed as not planned, which decides its section.

5. Scan git history

Search the git log for upstream references not yet found:

git log --all --oneline --grep="github.com/" | head -100

Search the codebase for inline issue references:

grep -rn 'github\.com/.*/\(issues\|pull\)/' src/ lib/ --include="*.py" | grep -v __pycache__

Also check docs/ and any changelog for upstream references.