Skip to content

Process: Require documentation updates (or explicit opt-out) for all PRs #1815

@pgrayy

Description

@pgrayy

Problem

We've noticed several features released over the last couple of months that aren't documented on the docs website. This includes both "fix" PRs that introduce new behavior (e.g. #1808) and external contributions that we've merged without corresponding documentation updates.

The current PR checklist has documentation items, but they're easy to skip without explanation, which means features ship undocumented.

Proposal

Add a requirement to the contribution/review process so that PRs must either:

  1. Include documentation updates (to the docs website repo), or
  2. Explicitly opt out of documentation with a written explanation of why docs aren't needed.

If neither is provided, the issue should not be considered closeable until documentation is addressed.

Suggested Actions

  • Update the PR template to make the documentation opt-out explicit (e.g. a required field: "Documentation not needed because: ___")
  • Update the review checklist so reviewers verify documentation status before approving
  • Consider a CI check or label (e.g. needs-docs, docs-not-required) to track documentation status on PRs
  • Audit recently merged PRs for missing documentation and create follow-up issues as needed

Context

From team discussion — cc @pgrayy @maczas

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions