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-review

When 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 pages

What 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/fix on 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.

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+.

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-review

When 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 pages

What 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/fix on 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.

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+.

Contribution Guidelines

Search Documentation

Contribution Guidelines