chore: drop upstream gsd issue and pr governance
Some checks failed
Tests / lint-tests (push) Has been cancelled
Tests / plugin-validate (push) Has been cancelled
Tests / test (ubuntu-latest, 24, shard 1/3) (push) Has been cancelled
Tests / test (ubuntu-latest, 24, shard 2/3) (push) Has been cancelled
Tests / test (ubuntu-latest, 24, shard 3/3) (push) Has been cancelled
Tests / test (ubuntu-latest, 24) (push) Has been cancelled
Tests / test (inert CI) (push) Has been cancelled
Tests / conformance test (macos-latest, 24) (push) Has been cancelled
Tests / conformance test (windows-latest, 24, shard 1/3) (push) Has been cancelled
Tests / conformance test (windows-latest, 24, shard 2/3) (push) Has been cancelled
Tests / conformance test (windows-latest, 24, shard 3/3) (push) Has been cancelled
Tests / Coverage gate (merged shards) (push) Has been cancelled
Tests / QA loop walk (smell ratchet) (push) Has been cancelled
Tests / Required tests (push) Has been cancelled
Tests / Publish emitted-baseline artifact (push) Has been cancelled
Tests / PR mergeability (push) Has been cancelled
Tests / Base branch health (push) Has been cancelled
Tests / Detect test scope (push) Has been cancelled
Some checks failed
Tests / lint-tests (push) Has been cancelled
Tests / plugin-validate (push) Has been cancelled
Tests / test (ubuntu-latest, 24, shard 1/3) (push) Has been cancelled
Tests / test (ubuntu-latest, 24, shard 2/3) (push) Has been cancelled
Tests / test (ubuntu-latest, 24, shard 3/3) (push) Has been cancelled
Tests / test (ubuntu-latest, 24) (push) Has been cancelled
Tests / test (inert CI) (push) Has been cancelled
Tests / conformance test (macos-latest, 24) (push) Has been cancelled
Tests / conformance test (windows-latest, 24, shard 1/3) (push) Has been cancelled
Tests / conformance test (windows-latest, 24, shard 2/3) (push) Has been cancelled
Tests / conformance test (windows-latest, 24, shard 3/3) (push) Has been cancelled
Tests / Coverage gate (merged shards) (push) Has been cancelled
Tests / QA loop walk (smell ratchet) (push) Has been cancelled
Tests / Required tests (push) Has been cancelled
Tests / Publish emitted-baseline artifact (push) Has been cancelled
Tests / PR mergeability (push) Has been cancelled
Tests / Base branch health (push) Has been cancelled
Tests / Detect test scope (push) Has been cancelled
MSD does not use an issue tracker, and the inherited GSD community gates auto-closed PR #1 for lacking an issue-numbered title. Remove them: - workflows: require-issue-link, pr-title-validator, auto-close-unsolicited-prs, pr-template-format, close-draft-prs(-sweep), auto-label-issues, auto-branch, duplicate-check, duplicate-sweep, remove-duplicate-label - GSD PR and issue templates, plus the scripts only they used (require-issue-link-policy, pr-template-policy, pr-changed-files) and their tests - workflow lists in ci-test-scope, ci-pr-mergeability, workflow-maintainer-skip, lint-pr-check-project-dir, the docs-guard baseline and the conformance tiers - CONTRIBUTING: PR-against-next flow with no issue or template; PR titles are conventional without an issue ref; ADR/PRD files use the PR number - CONTEXT.md: drop the PR-template predicates (k328, templates-mandatory)
This commit is contained in:
130
CONTRIBUTING.md
130
CONTRIBUTING.md
@@ -29,95 +29,39 @@ environment validator, daily commands, and troubleshooting.
|
||||
|
||||
---
|
||||
|
||||
## Types of Contributions
|
||||
## How Changes Land
|
||||
|
||||
MSD accepts three types of contributions. Each type has a different process and a different bar for acceptance. **Read this section before opening anything.**
|
||||
MSD is maintained by a small team and does not use an issue tracker. Work happens on a feature branch and lands through a pull request against `next` on [git.golem15.com](https://git.golem15.com/golem15/msd-core):
|
||||
|
||||
### 🐛 Fix (Bug Report)
|
||||
1. Branch from `next` (`feat/<slug>`, `fix/<slug>`, `chore/<slug>`, …).
|
||||
2. Make the change, with tests. Add a `.changeset/` fragment if it is user-facing (see below).
|
||||
3. Open a PR against `next`. Describe what changed and why, and how you tested it. No issue link or PR template is required.
|
||||
4. Merge once CI is green and the change is reviewed.
|
||||
|
||||
A fix corrects something that is broken, crashes, produces wrong output, or behaves contrary to documented behavior.
|
||||
|
||||
**Process:**
|
||||
1. Open a [Bug Report issue](https://github.com/open-gsd/gsd-core/issues/new?template=bug_report.yml) — fill it out completely.
|
||||
2. Wait for a maintainer to confirm it is a bug (label: `confirmed-bug`). For obvious, reproducible bugs this is typically fast.
|
||||
3. Fix it. Write a test that would have caught the bug.
|
||||
4. Open a PR using the [Fix PR template](.github/PULL_REQUEST_TEMPLATE/fix.md) — link the confirmed issue.
|
||||
|
||||
**Rejection reasons:** Not reproducible, works-as-designed, duplicate of an existing issue.
|
||||
|
||||
---
|
||||
|
||||
### ⚡ Enhancement
|
||||
|
||||
An enhancement improves an existing feature — better output, faster execution, cleaner UX, expanded edge-case handling. It does **not** add new commands, new workflows, or new concepts.
|
||||
|
||||
**The bar:** Enhancements must have a scoped written proposal approved by a maintainer before any code is written. A PR for an enhancement will be closed without review if the linked issue does not carry the `approved-enhancement` label.
|
||||
|
||||
**Process:**
|
||||
1. Open an [Enhancement issue](https://github.com/open-gsd/gsd-core/issues/new?template=enhancement.yml) with the full proposal. The issue template requires: the problem being solved, the concrete benefit, the scope of changes, and alternatives considered.
|
||||
2. **Wait for maintainer approval.** A maintainer must label the issue `approved-enhancement` before you write a single line of code. Do not open a PR against an unapproved enhancement issue — it will be closed.
|
||||
3. Write the code. Keep the scope exactly as approved. If scope creep occurs, comment on the issue and get re-approval before continuing.
|
||||
4. Open a PR using the [Enhancement PR template](.github/PULL_REQUEST_TEMPLATE/enhancement.md) — link the approved issue.
|
||||
|
||||
**Rejection reasons:** Issue not labeled `approved-enhancement`, scope exceeds what was approved, no written proposal, duplicate of existing behavior.
|
||||
|
||||
---
|
||||
|
||||
### ✨ Feature
|
||||
|
||||
A feature adds something new — a new command, a new workflow, a new concept, a new integration. Features have the highest bar because they add permanent maintenance burden to a solo-developer tool maintained by a small team.
|
||||
|
||||
**The bar:** Features require a complete written specification approved by a maintainer before any code is written. A PR for a feature will be closed without review if the linked issue does not carry the `approved-feature` label. Incomplete specs are closed, not revised by maintainers.
|
||||
|
||||
**Process:**
|
||||
1. **Discuss first** — check [Discussions](https://github.com/open-gsd/gsd-core/discussions) to see if the idea has been raised. If it has and was declined, don't open a new issue.
|
||||
2. Open a [Feature Request issue](https://github.com/open-gsd/gsd-core/issues/new?template=feature_request.yml) with the complete spec. The template requires: the solo-developer problem being solved, what is being added, full scope of affected files and systems, user stories, acceptance criteria, and assessment of maintenance burden.
|
||||
3. **Wait for maintainer approval.** A maintainer must label the issue `approved-feature` before you write a single line of code. Approval is not guaranteed — MSD is intentionally lean and many valid ideas are declined because they conflict with the project's design philosophy.
|
||||
4. Write the code. Implement exactly the approved spec. Changes to scope require re-approval.
|
||||
5. Open a PR using the [Feature PR template](.github/PULL_REQUEST_TEMPLATE/feature.md) — link the approved issue.
|
||||
|
||||
**Rejection reasons:** Issue not labeled `approved-feature`, spec is incomplete, scope exceeds what was approved, feature conflicts with MSD's solo-developer focus, maintenance burden too high.
|
||||
Releases are cut from `next` as `vX.Y.Z` tags; the `stable` branch follows the latest release (see `CLAUDE.md`, "Distribution and releases").
|
||||
|
||||
---
|
||||
|
||||
### 📐 Proposing an ADR or PRD
|
||||
|
||||
An ADR (Architecture Decision Record) documents a significant architectural decision. A PRD (Product Requirements Document) captures the what and why of a feature before implementation. Both are governed by the same issue-first rule as everything else.
|
||||
An ADR (Architecture Decision Record) documents a significant architectural decision. A PRD (Product Requirements Document) captures the what and why of a feature before implementation.
|
||||
|
||||
**Process:**
|
||||
|
||||
1. Open an issue of the appropriate type (enhancement for an ADR revisiting an existing area, feature for a new architectural surface, chore for policy/docs decisions). Fill it out completely.
|
||||
2. **Wait for maintainer approval.** A maintainer must label the issue `approved-enhancement`, `approved-feature`, or confirm the chore before any file is created.
|
||||
3. The GitHub-assigned issue number becomes your filename prefix. Create the file on a branch named after the issue:
|
||||
- `docs/adr/<issue#>-<slug>.md` for ADRs
|
||||
- `docs/prd/<issue#>-<slug>.md` for PRDs
|
||||
- Branch: `docs/<issue#>-<slug>`
|
||||
4. Open a PR using the appropriate template and close the issue with `Closes #<issue#>` in the PR body.
|
||||
1. Open the PR that adds the file (it can start as just the document) so it gets a number.
|
||||
2. Use that PR number as the filename prefix:
|
||||
- `docs/adr/<pr#>-<slug>.md` for ADRs
|
||||
- `docs/prd/<pr#>-<slug>.md` for PRDs
|
||||
3. Agree on the decision in the PR before building on it.
|
||||
|
||||
**One issue = one ADR-or-PRD = one PR.** Do not batch multiple decisions into one file or one PR.
|
||||
**One ADR-or-PRD per PR.** Do not batch multiple decisions into one file or one PR.
|
||||
|
||||
**Do not compute a "next number" locally.** Any PR that uses the legacy `NNNN-*` sequential pattern for a *new* ADR or PRD will be asked to rename the file to the `<issue#>-<slug>.md` format before merge.
|
||||
|
||||
**Example:** Issue #2264 was opened, approved, and its number became the prefix: `docs/adr/2264-golden-parity-redesign.md`.
|
||||
|
||||
**Rejection reasons:** Issue not approved before file was created, filename uses local-compute sequential number instead of issue#, multiple decisions bundled in one PR, file placed in wrong directory (`docs/adr/` vs `docs/prd/`).
|
||||
**Do not compute a "next number" locally** — the PR number is unique, a locally guessed sequence is not. Existing files keep the upstream issue numbers they were created with.
|
||||
|
||||
**This process is for a *new* ADR file.** An accepted ADR is never rewritten from scratch — check `docs/adr/` first for a broader ADR that already owns the area. Amending one is a separate, lighter-weight path: see **[`docs/contributor-standards.md` — "Amending an accepted ADR"](docs/contributor-standards.md#amending-an-accepted-adr)** for the two established patterns (an in-place dated section, or a new ADR that declares `Amends`/gets the reciprocal `Amended by` back-link).
|
||||
|
||||
---
|
||||
|
||||
## The Issue-First Rule — No Exceptions
|
||||
|
||||
> **No code before approval.**
|
||||
|
||||
For **fixes**: open the issue, confirm it's a bug, then fix it.
|
||||
For **enhancements**: open the issue, get `approved-enhancement`, then code.
|
||||
For **features**: open the issue, get `approved-feature`, then code.
|
||||
|
||||
PRs that arrive without a properly-labeled linked issue are closed automatically. This is not a bureaucratic hurdle — it protects you from spending time on work that will be rejected, and it protects maintainers from reviewing code for changes that were never agreed to.
|
||||
|
||||
---
|
||||
|
||||
## Where Do I Open My PR? (Branching Model)
|
||||
|
||||
MSD uses two long-lived branches: `main` (production, what's on npm `@latest`)
|
||||
@@ -182,23 +126,15 @@ Contributor requirements (summary):
|
||||
- Read `CONTEXT.md` before naming or refactoring modules/interfaces/seams.
|
||||
- Use `CONTEXT.md` vocabulary consistently in code comments, tests, issue/PR text, and docs for the touched area.
|
||||
- Check relevant ADRs in `docs/adr/` before proposing or implementing architectural changes.
|
||||
- If a change intentionally revisits an ADR decision, call it out explicitly in the linked issue and PR rationale.
|
||||
- If a change intentionally revisits an ADR decision, call it out explicitly in the PR rationale.
|
||||
- Do not rewrite maintainer intent in `CONTEXT.md`/ADRs as part of drive-by cleanup; propose focused updates tied to approved scope.
|
||||
- If using an AI assistant, prompt it to read `CONTEXT.md` and the relevant ADRs before writing any code or docs, and verify it used the correct vocabulary before opening the PR.
|
||||
|
||||
**Every PR must link to an approved issue.** PRs without a linked issue are closed without review, no exceptions.
|
||||
|
||||
- **No draft PRs** — draft PRs are automatically closed. Only open a PR when it is complete, tested, and ready for review. If your work is not finished, keep it on your local branch until it is.
|
||||
- **Use the correct PR template** — there are separate templates for [Fix](.github/PULL_REQUEST_TEMPLATE/fix.md), [Enhancement](.github/PULL_REQUEST_TEMPLATE/enhancement.md), and [Feature](.github/PULL_REQUEST_TEMPLATE/feature.md). Using the wrong template or using the default template for a feature is a rejection reason.
|
||||
- **Link with a closing keyword** — use `Closes #123`, `Fixes #123`, or `Resolves #123` in the PR body. The CI check will fail and the PR will be auto-closed if no valid issue reference is found.
|
||||
- **Test-only and docs-only follow-up PRs may reference without closing.** If your PR is documentation or regression coverage only — say, a repo-wide guard for a fix that already shipped — and there is no open issue for it to close, use a non-closing reference instead: `Refs #123`. `Ref`, `Refs`, `References`, `Relates to`, `Related to`, and `Follow-up to` are all accepted in that position. Do **not** write a closing keyword against an already-closed issue to satisfy the check; on merge it closes nothing, and it trains readers to treat closing keywords as decorative.
|
||||
- **Qualifying diff shape:** every changed file must be under `tests/`, under `docs/`, or a root-level `*.md` (`README.md`, `CONTRIBUTING.md`, …). This mirrors the doc-only classification the push gate already uses, and it is deliberately root-only — markdown under a subdirectory (`msd-core/workflows/*.md`, `agents/*.md`, `commands/**/*.md`) is runtime-loaded text, not documentation, so it still requires a closing keyword. `CHANGELOG.md` is excluded too: edit it through a `.changeset/` fragment, never directly.
|
||||
- This weaker form is accepted **only** for that diff shape. A PR touching anything else still needs a closing keyword, and a PR with no issue reference at all still fails. On a very large PR (more than 100 changed files) the check cannot confirm the diff shape and falls back to requiring a closing keyword.
|
||||
- **One concern per PR** — bug fixes, enhancements, and features must be separate PRs
|
||||
- **No drive-by formatting** — don't reformat code unrelated to your change
|
||||
- **Don't bundle test-fixture updates into `docs:` or unrelated commits** — when a production change makes an existing test assertion stale, the test correction MUST land as its own `test:` (or `fix:`) commit, not bundled into a `docs:` commit that also updates the explanation. The release-sdk hotfix cherry-pick filter routes by commit-subject prefix (`fix:`, `chore:`, `test:`); a test-fixture correction packed under a `docs:` prefix is invisible to the picker and ships a half-state to the hotfix branch — production code changed, test assertion stale. v1.42.3 hit this exact mode (#3621). The fix is upstream: keep the test-fixture commit separate.
|
||||
- **CI must pass** — all configured matrix jobs must be green. Node 24 is the compatibility floor and primary target; Node 26 compatibility must be preserved for code and tests even when a Node 26 CI lane is not yet available.
|
||||
- **Scope matches the approved issue** — if your PR does more than what the issue describes, the extra changes will be asked to be removed or moved to a new issue
|
||||
- **Scope matches the PR description** — unrelated changes go in their own PR
|
||||
|
||||
## CHANGELOG Entries — Drop a Fragment
|
||||
|
||||
@@ -244,32 +180,18 @@ node scripts/release-notes/format-github-release-notes.cjs \
|
||||
Omit `--apply` to print the reformatted body to stdout for review without
|
||||
publishing.
|
||||
|
||||
### PR title convention (enforced at open time)
|
||||
### PR title convention
|
||||
|
||||
Because the changelog is built from PR titles, your **PR title** must follow:
|
||||
Because the GitHub-style release notes are grouped by PR title, start the title with a conventional type:
|
||||
|
||||
```
|
||||
type(#<issue>): short summary
|
||||
type: short summary
|
||||
```
|
||||
|
||||
- **Start with the type** — `feat`, `fix`, or any other conventional type
|
||||
(`chore`, `docs`, `refactor`, …). No leading tags or prefixes: a title like
|
||||
`[security] fix(config): …` defeats the `^fix` bucket anchor and silently
|
||||
files the entry under the wrong changelog section.
|
||||
- **Put the linked issue ref in the scope** — `(#<digits>)`. This is what
|
||||
renders as a link to the issue in the changelog line. `fix(core): …` buckets
|
||||
correctly but produces a changelog entry with **no issue link**.
|
||||
- A breaking-change marker is fine: `feat(#42)!: …`.
|
||||
- **Start with the type** — `feat`, `fix`, or any other conventional type (`chore`, `docs`, `refactor`, …). No leading tags: a title like `[security] fix: …` defeats the `^fix` anchor and files the entry under the wrong section.
|
||||
- A scope and a breaking-change marker are fine: `fix(installer): …`, `feat!: …`.
|
||||
|
||||
Examples: `fix(#1542): roadmap rollback`, `feat(#39): milestone-prefixed phase IDs`,
|
||||
`enhance(#1549): add PR-title validator`.
|
||||
|
||||
**CI enforcement:** `pr-title-validator.yml` checks the title on open/edit and
|
||||
fails with the required format if it doesn't conform. It reuses the same matcher
|
||||
the changelog classifier uses (`scripts/release-notes/conventional-title.cjs`), so a title
|
||||
that passes the check is guaranteed to bucket and link correctly. Fix a flagged
|
||||
title by editing it in place — the check re-runs on edit, no need to recreate
|
||||
the PR.
|
||||
Nothing enforces this in CI; `scripts/release-notes/conventional-title.cjs` is the matcher the release notes use.
|
||||
|
||||
## Documentation Updates — Update the Relevant Docs
|
||||
|
||||
@@ -347,7 +269,7 @@ shared file, so there is nothing to collide on.
|
||||
|
||||
1. **Any unique `id` is legal.** It does not have to be contiguous or maximal —
|
||||
58, 113 and 131 are already absent, and `6.5`, `27a` and `27b` are live
|
||||
non-integer ids. **Use your issue number** and you never have to revisit the
|
||||
non-integer ids. **Use your PR number** and you never have to revisit the
|
||||
choice after a rebase. `--check` rejects a duplicate with an `id_duplicate`
|
||||
violation naming both fragments, so a collision is a loud one-line fix in
|
||||
your own file, not a merge conflict.
|
||||
@@ -373,7 +295,7 @@ shared file, so there is nothing to collide on.
|
||||
rejects it (`body_heading_too_shallow`).
|
||||
|
||||
**Fork contributors:** there is nothing to coordinate and nothing to chase. Pick
|
||||
your issue number, add your file, regenerate. If `docs/FEATURES.md` conflicts on
|
||||
your PR number, add your file, regenerate. If `docs/FEATURES.md` conflicts on
|
||||
a rebase, discard your side and re-run `--write` — it is a derived artifact.
|
||||
|
||||
**Agents:** no Fleet allocation lease is needed for a feature number any more.
|
||||
@@ -1361,7 +1283,7 @@ Reviewers do not rely solely on CI to verify correctness. Before approving a PR,
|
||||
- Build locally (`npm run build` if applicable)
|
||||
- Run the full test suite locally (`npm test`)
|
||||
- Confirm regression tests exist for bug fixes and that they would fail without the fix
|
||||
- Validate that the implementation matches what the linked issue described — green CI on the wrong implementation is not an approval signal
|
||||
- Validate that the implementation matches what the PR description says — green CI on the wrong implementation is not an approval signal
|
||||
|
||||
**"Tests pass in CI" is not sufficient for merge.** The implementation must correctly solve the problem described in the linked issue.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user