Skip to content

docs: add CONTRIBUTING.md#42

Open
pbegg wants to merge 1 commit intoWoyken:mainfrom
pbegg:docs/contributing-guide
Open

docs: add CONTRIBUTING.md#42
pbegg wants to merge 1 commit intoWoyken:mainfrom
pbegg:docs/contributing-guide

Conversation

@pbegg
Copy link
Copy Markdown

@pbegg pbegg commented Apr 21, 2026

Summary

Adds a CONTRIBUTING.md at the repo root documenting the external-contributor workflow. There isn't one today, so the process is implicit and has to be inferred from the README's Development section and recent merged PRs. This draft makes it explicit.

Raising the PR itself (rather than an issue) so you can react to concrete wording — feel free to request any changes, trim, or reject outright if you'd prefer not to have one.

What it covers

  • Fork + upstream remote setup; syncing main before branching.
  • Loose branch naming (matching the style of recent PRs).
  • Use of uv for all Python commands (consistent with AGENTS.md rule 3).
  • The exact local checks that PR Validation enforces: ruff check, ruff format --check, ty check --python-version 3.14 --ignore unknown-argument.
  • Towncrier fragment requirement, location (newsfragments/), filename format (<id-or-slug>.<type>.md), and types (feature, bugfix, doc, removal, misc).
  • Integration tests caveat — fork PRs can't access repo secrets, so that workflow won't produce full results on external PRs.
  • Release process note so contributors understand towncrier build is maintainer-only.

What it deliberately doesn't do

  • Doesn't duplicate the coding rules in AGENTS.md — it references it as the source of truth.
  • Doesn't introduce a DCO, CLA, signed-commit requirement, or explicit Code of Conduct. Happy to add any of these if you want them.
  • Doesn't change any CI or existing files — only adds CONTRIBUTING.md and a towncrier doc fragment.

Things worth your call

  • Location: repo root vs .github/CONTRIBUTING.md — I went with root for discoverability.
  • Branch-naming: left informal to match existing practice. Happy to prescribe something stricter if you'd prefer.
  • Commit-message style: not specified. If you want conventional commits or another convention enforced, let me know and I'll add a section.

Test plan

  • CONTRIBUTING.md renders correctly on GitHub
  • Towncrier fragment added at newsfragments/contributing-guide.doc.md following existing convention
  • PR Validation (ruff + ty + towncrier check) passes on CI
  • Integration Tests workflow status observed (expected to be skipped/degraded on fork PR)

Documents the fork-and-PR workflow, required local checks (ruff, ty),
and the towncrier fragment convention for external contributors. References
AGENTS.md as the source of truth for coding rules rather than duplicating
them.
@pbegg pbegg mentioned this pull request Apr 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant