Docs: add a first-contribution workflow for docs-only contributors
Open 💬 4 comments Opened Jun 19, 2026 by kmishra1204
What is missing today
The repo has docs/contributing.md and issue templates, which is great. A small missing piece is a single "first external contribution" path for docs contributors that tells new users exactly what to do in sequence.
Suggested improvement
Add a short section in README.md (or top of docs/contributing.md) called "First Contribution (Docs)" with:
- how to choose a docs issue
- local docs validation command(s)
- expected PR structure and checklist
- what reviewers usually look for
Why this is useful
Codex has very high visibility and issue volume; a streamlined docs-first path could reduce contributor friction and improve quality of first PRs.
If useful, I can propose a concrete patch to docs/contributing.md.
4 Comments
Adding a concrete draft structure that might be easy to adopt:
Who can contribute(issue-first, invited code PR policy)Fast path for docs-only contributors(how to propose wording, expected evidence, minimal checks)Bug triage contribution template(repro, expected/actual behavior, logs)When maintainers invite a PR(criteria and handoff expectations)This could preserve the current invitation-only policy while still giving external contributors a clearer path to contribute useful analysis/docs.
Quick implementation draft to reduce maintainer review overhead:
docs/contributing.mdwith a 4-step path (find issue -> propose wording -> run checks -> open PR).If useful, I can open a docs-only patch with these exact section headings so review can stay small and fast.
Given the current
docs/contributing.mdpolicy says external code contributions are invitation-only, I think this docs change should avoid telling first-time contributors to open unsolicited PRs. A lower-friction section could be issue-first and still give maintainers copy-ready material.Suggested text shape:
That would cover docs-only contributors without conflicting with the invite-only PR rule. It also gives bug triagers a clear path to contribute value even when opening a PR is not appropriate.
Quick follow-up with a maintainer-friendly minimal shape (if this direction still fits):
Suggested docs block: "First contribution path (docs-only)"
CONTRIBUTING.md+ docs index)This keeps onboarding lightweight while still preserving review quality and traceability for contributors who are not changing runtime code.