mirror of https://github.com/Fission-AI/OpenSpec.git synced 2026-09-14 20:16:53 +08:00

Files

T

Clay Good 1c0ee701e5 docs: add CONTRIBUTING.md (#1781 )

* docs: add CONTRIBUTING.md

Require a discussion (core design changes) or an issue before a PR is
opened, and require every PR to link its issue.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs: add setup and PR steps to CONTRIBUTING.md

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs: make CONTRIBUTING.md the single source for the process

The README's Contributing section said small fixes could go straight to
a PR, which contradicts the new discussion/issue requirement. Point it at
CONTRIBUTING.md and carry over the conventional-commit and AI-disclosure
policies so nothing is lost.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs: close the three process gaps in CONTRIBUTING.md

alfred-openspec on #1781:

1. The OpenSpec-proposal rule was dropped from the README with nothing
   replacing it, recreating the gap in #1727. New step 2 carries the threshold
   over verbatim from the README (new features, significant refactors,
   architectural changes) plus the philosophy paragraph, says to open the
   proposal as its own PR and wait for approval, and tells anyone unsure to ask
   in the issue from step 1.

2. The discussion path contradicted itself: step 1 accepted a prior discussion
   while step 3 required 'Closes #123'. The PR step now says to link what you
   opened in step 1, 'Closes #123' for an issue or a link to the discussion
   when there is no issue. CodeRabbit's thread on README.md:227 is the same
   defect, so the README sentence says 'the issue or discussion' too.

3. The local setup was missing 'pnpm exec tsc --noEmit', which CI runs, and the
   README called the guide a development setup after 'pnpm run dev' and
   'dev:cli' were removed. The command is added, the guide states that those
   four commands are exactly what CI runs, and the README pointer now describes
   the guide as the full process rather than a setup.

Verified each documented command against this checkout: build, tsc --noEmit and
lint all pass as written.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

2026-09-09 16:24:45 +00:00

2.0 KiB

Raw Permalink Blame History

Contributing

Thanks for helping improve OpenSpec.

1. Open a discussion or an issue first

Every change starts here, including small ones.

Start a discussion if it affects OpenSpec's core design.
Open an issue for bugs and everything else.

This is so we can agree on the approach before you spend time building. PRs without a linked issue or a prior discussion may be closed.

2. Decide whether it needs a change proposal

A bug fix, a typo, or a small improvement goes straight to a PR.

A new feature, a significant refactor, or anything that changes OpenSpec's architecture needs an OpenSpec change proposal first, so we can align on intent and goals before implementation begins. Open it as a PR containing only openspec/changes/<name>/ and wait for it to be approved before you write the code.

When writing a proposal, keep the OpenSpec philosophy in mind: we serve a wide variety of users across different coding agents, models, and use cases. Changes should work well for everyone.

If you are not sure which side of the line your change falls on, ask in the discussion or issue from step 1.

3. Make your change

You need Node 20.19+ and pnpm.

pnpm install
pnpm build              # tests run against the build output
pnpm test
pnpm exec tsc --noEmit
pnpm lint

Those four commands are what CI runs, so a green local run means a green CI run.

Run pnpm changeset if your change affects users, and commit the file it generates.

4. Open the PR

Branch off main in your fork.
Title it as a conventional commit: type(scope): subject, for example fix(archive): keep authored Purpose.
Link what you opened in step 1: Closes #123 for an issue, or a link to the discussion when there is no issue.
If a coding agent wrote the code, say which agent and model, and confirm you tested it. AI-generated code is welcome when it has been verified.

Maintainers are listed in MAINTAINERS.md.