Contribution Guidelines
Contribution guidelines define how changes land in Python service repos and this SME knowledge base: branch naming, PR expectations, review rules, and CODEOWNERS - so maintenance scales beyond one author.
Recipe
Quick-reference recipe card - copy-paste ready.
## Pull request template
### Intent
### Risk (migration/security/perf)
### Test evidence (`uv run pytest path`)
### Rollback plan
### Links (RFC, ADR, ticket)# CODEOWNERS
/src/billing/ @billing-team
/docs/runbooks/ @sre-oncall
/alembic/ @billing-team @dba-reviewWhen to reach for this:
- Open-sourcing internal library
- SME cookbook external contributions
- New engineers asking "how do I PR?"
- Audit of change control
Working Example
# Contributor workflow (internal)
git checkout -b feat/ENG-550-billing-retry
uv sync
uv run pytest tests/billing -q
uv run ruff check .
git commit -m "feat(billing): exponential backoff on transient DB errors"
git push -u origin feat/ENG-550-billing-retry
# Open PR; fill template; request CODEOWNERS review## SME cookbook contribution (site/python/)
- One article per PR when possible
- Frontmatter: unique tags, correct section slug
- Run `npx tsx scripts/lint-docs.ts`
- No em dash; stack footer last line
- Relative links only to existing pagesWhat this demonstrates:
- Local quality gates before PR
- Commit message links domain for changelog tools
- CODEOWNERS auto-requests billing + DBA for migrations
- Docs contributions have explicit lint step
Deep Dive
How It Works
- Branch naming -
feat/,fix/,chore/+ ticket id. - Review policy - One approval default; two for security/migrations.
- CI required - pytest, ruff, pyright (changed paths), image build optional.
- Merge strategy - Squash merge for linear history; SHA tagged on deploy.
- External contributors - Fork PR; CLA bot if open source.
Contribution Types
| Type | Extra requirement |
|---|---|
| Feature | Spec link if M/L |
| Migration | Expand-contract review |
| Dependency | pip-audit clean |
| Docs only | lint-docs green |
Python Notes
# .github/workflows/ci.yml excerpt
- run: uv sync --frozen
- run: uv run pytest
- run: uv run ruff check .Gotchas
- Merge without CODEOWNER review - Bypasses expertise. Fix: Branch protection rules.
- Giant drive-by PRs - Unreviewable. Fix: Split by vertical slice.
- Skipping tests "docs only" - Broken links ship. Fix: lint-docs mandatory.
- Direct push to main - CFR rises. Fix: Protect main; release from tags.
- No rollback note - On-call stuck. Fix: Template field required for
feat/fixon services.
Alternatives
| Alternative | Use When | Don't Use When |
|---|---|---|
| Trunk-based pair commit | Tiny senior team | Regulated separation of duties |
| Fork even for internals | Open source style | Private monorepo trust culture |
| Release branches | Long support versions | Continuous deploy main |
| No CODEOWNERS | Solo maintainer | Multi-team monorepo |
FAQs
Who can approve migrations?
Service CODEOWNER + DBA reviewer group per policy.
Dependabot PRs?
Auto-merge patch if CI green; minor reviewed weekly.
Hotfix process?
Branch from tag; PR with reduced DoD; backport to main.
Contributing to cookbook?
Follow sme-content-article/list shapes; manifest category python.
Signed commits?
Optional; required if org policy mandates.
Issue before PR?
Encouraged for large work; small fixes OK with PR only.
License for OSS libs?
Apache-2.0 or MIT per legal; LICENSE file required.
Co-authored commits?
Pairing credit encouraged; both reviewed PR.
Stale PR policy?
Close after 30d inactive; author reopen when ready.
Security disclosures?
Private channel per SECURITY.md; no public issue for vulns.
Related
- Code Review Culture - review norms
- Documentation Conventions - doc PRs
- Dependency & Supply-Chain Governance - dep PRs
- Coding Standards & Style Guides - CI standards
- Git & GitHub - git workflow
Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.