jedarden 97fecb7b4b docs(contributing): add Argo-CI caveat, DCO sign-off, and contributor templates

- Restructured CONTRIBUTING.md with all nine required sections:
  - Project licensing (MIT OR Apache-2.0, DCO sign-off required)
  - Code of conduct (Contributor Covenant v2.1)
  - Security reporting (link to SECURITY.md)
  - Development setup (with OCR dependencies)
  - Local validation checklist (6 commands matching pdftract-ci)
  - CI on forks caveat (maintainer-triggered, 48-hour response)
  - PR template requirements
  - Commit message style (Conventional Commits)
  - Issue triage

- Created CODE_OF_CONDUCT.md (Contributor Covenant v2.1)

- Created .github/PULL_REQUEST_TEMPLATE.md with required fields:
  - Linked issue or RFC
  - Scope statement (Phase / Acceptance Scenario)
  - Test plan
  - Manual-test evidence
  - Performance impact

- Created issue templates:
  - bug_report.md (with pdftract doctor output requirement)
  - feature_request.md (with use case and proposed solution)
  - performance_regression.md (with baseline vs current)

- Updated README.md with Contributing section linking to CONTRIBUTING.md

- Added footer links to CONTRIBUTING.md in all templates

Closes: pdftract-i9rk

Verification: notes/pdftract-i9rk.md
Signed-off-by: jedarden <github@jedarden.com>

2026-05-24 06:00:48 -04:00

2.9 KiB

Raw Permalink Blame History

Verification Note: pdftract-i9rk

Bead

CONTRIBUTING.md — Argo-CI caveat for forks, local validation checklist, PR template requirements

Summary

Created and updated contributor documentation to ensure first-time contributors can submit properly-formatted PRs without surprises.

Files Created/Modified

Created:

CODE_OF_CONDUCT.md — Contributor Covenant v2.1 (5,519 bytes)
.github/PULL_REQUEST_TEMPLATE.md — PR template with required fields (1,988 bytes)
.github/ISSUE_TEMPLATE/bug_report.md — Bug report template (1,532 bytes)
.github/ISSUE_TEMPLATE/feature_request.md — Feature request template (1,373 bytes)
.github/ISSUE_TEMPLATE/performance_regression.md — Performance regression template (1,974 bytes)

Modified:

CONTRIBUTING.md — Completely restructured with all required sections (11,294 bytes)
README.md — Added Contributing section with link to CONTRIBUTING.md

Acceptance Criteria Status

PASS

CONTRIBUTING.md exists at repo root
All nine sections from bead description are present:
1. Project licensing (dual MIT OR Apache-2.0)
2. Code of conduct (link to CODE_OF_CONDUCT.md)
3. Reporting security issues (link to SECURITY.md)
4. Development setup (with OCR dependencies for Phase 5 features)
5. Local validation expected before opening a PR (6 commands matching pdftract-ci)
6. CI on forks (the Argo-CI caveat)
7. PR template requirements
8. Commit message style (Conventional Commits)
9. Issue triage
The Argo-CI caveat is in a clearly visible Markdown blockquote (> **IMPORTANT:**)
Local-validation commands exactly match the pdftract-ci workflow steps
A first-time contributor can read CONTRIBUTING.md and submit a properly-formatted PR without surprises
Linked from README (Contributing section added)
Linked from .github/ISSUE_TEMPLATE/ (all templates have footer links)
Linked from PR template (footer link added)

Key Features Implemented

DCO sign-off requirement clearly documented with git commit -s example
48-hour maintainer-triggered CI response window documented
Argo-CI caveat explains why external forks cannot self-trigger CI
Local validation checklist matches CI workflow: test, clippy, bloat, audit, deny, fmt
Conventional Commits format documented with examples
All issue templates include link to CONTRIBUTING.md

Files Modified

CONTRIBUTING.md (restructured)
README.md (added Contributing section)
CODE_OF_CONDUCT.md (created)
.github/PULL_REQUEST_TEMPLATE.md (created)
.github/ISSUE_TEMPLATE/bug_report.md (created)
.github/ISSUE_TEMPLATE/feature_request.md (created)
.github/ISSUE_TEMPLATE/performance_regression.md (created)

No WARN/FAIL

All acceptance criteria met.

References

Plan section: Release Engineering / Contributor Workflow, lines 3424-3433
ADR-009 (Argo-only CI explains the fork caveat)
Bead: pdftract-i9rk

2.9 KiB Raw Permalink Blame History