Skip to content

docs: say when a contribution needs an OpenSpec change proposal first #1727

Description

@clay-good

The problem

OpenSpec asks its users to write a change proposal before building a feature. It doesn't say whether contributors to OpenSpec itself should do the same, or when.

In #1301, @m-tanner offered to write a change proposal before landing status --all, since it is a minor feature. There was no documented answer, so the question sat open while the PR was otherwise complete and green. The next contributor who opens a feature PR hits the same wall.

Why it matters

  • Contributors cannot tell whether they are missing a required step.
  • Reviewers decide case by case, and may decide differently.
  • A finished PR can stall on an unanswered process question rather than on its code.

Possible solutions

Pick one and write it into CONTRIBUTING.md:

  1. Threshold rule — a proposal is required when the changeset is minor or major (new user-facing surface), never for patch. Cheap to apply, and it reuses a classification every PR already makes.
  2. Maintainer-authored — contributors never need one; maintainers write the spec delta at archive time. Lowest friction for drive-by fixes.
  3. Automate it — a CI check that flags a minor+ changeset with no matching change under openspec/changes/. Best as a warning, not a block.

Suggested: start with (1), add (3) only if the question keeps recurring.

Notes

Not blocking #1301 or v1.11.0 — that PR is verified and ready to merge as-is. This is only about closing the process gap for the next contributor.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    backlogReal issue or feature queued for later implementationdesign-reviewNeeds product/design decision

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions