diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 80e65f4..0ff4398 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -24,6 +24,7 @@ Closes # - [ ] `pnpm test` passes (or targeted tests for my change) - [ ] `pnpm format` has been run - [ ] I have added/updated tests for my changes (if applicable) +- [ ] I have added a [changeset](https://github.com/emdash-cms/emdash/blob/main/CONTRIBUTING.md#changesets) (if this PR changes a published package) - [ ] New features link to an approved Discussion: https://github.com/emdash-cms/emdash/discussions/... ## AI-generated code disclosure diff --git a/AGENTS.md b/AGENTS.md index b1ace99..725fbc8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -54,12 +54,37 @@ Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR. Key rules: You verified linting and types were clean before starting. If they're failing now, your changes caused it -- even if the errors are in files you didn't touch. Don't dismiss failures as "unrelated". Don't assign blame. Just fix them. +### Changesets + +If your change affects a published package's behavior, add a changeset. Without one, the change won't trigger a package release. + +```bash +pnpm changeset --empty +``` + +This creates a blank changeset file in `.changeset/`. Edit it to add the affected package(s), bump type, and description: + +```markdown +--- +"emdash": patch +--- + +Fixes CLI `--json` flag so JSON output is clean. +``` + +Start descriptions with a present-tense verb (Adds, Fixes, Updates, Removes, Refactors). Focus on what changes for the user, not implementation details. + +Skip changesets for docs-only, test-only, CI, or demo/template changes. + +See [CONTRIBUTING.md § Changesets](CONTRIBUTING.md#changesets) for full guidance and examples. + ### PR Flow 1. All tests pass: `pnpm test` 2. Full lint suite clean: `pnpm --silent lint:json | jq '.diagnostics | length'`. Returns JSON with stderr piped to /dev/null, so it won't break parsers. Fix any issues. 3. Format with `pnpm format` (oxfmt with tabs for indentation, configured in `.prettierrc`). -4. Open the PR with the `pr` skill. Fill out every section of the PR template. Check the AI disclosure box. +4. Add a changeset if the change affects a published package: `pnpm changeset`. +5. Open the PR with the `pr` skill. Fill out every section of the PR template. Check the AI disclosure box. ### Dev Servers diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a5278d2..6445f48 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -215,6 +215,87 @@ We welcome AI-assisted contributions. They are held to the same quality bar as a - **Dependency upgrades** outside of Renovate/Dependabot. We manage these centrally. - **"Improvements"** to code you haven't been asked to change (added logging, extra error handling, style changes in unrelated files). +## Changesets + +Every PR that changes the behavior of a published package needs a **changeset** — a small Markdown file that describes the change for the CHANGELOG and determines the version bump. Without a changeset, the change won't trigger a package release. + +### When you need one + +- Bug fixes, features, refactors, or any other change that affects a published package's behavior or API. +- Changes that span multiple packages need one changeset listing all affected packages. +- If a PR makes more than one distinct change, add a separate changeset for each. Each one becomes its own CHANGELOG entry. + +### When you don't + +- Docs-only changes, test-only changes, CI/tooling changes, or changes to demo apps and templates (these are in the changeset ignore list). + +### How to add one + +Run from the repo root: + +```bash +pnpm changeset +``` + +This walks you through selecting the affected package(s), the semver bump type, and a description. It creates a randomly-named `.md` file in `.changeset/`. + +You can also create one manually — see the existing files in `.changeset/` for the format. + +### Writing the description + +Start with a present-tense verb describing what the change does, as if completing "This PR...": + +- **Adds** — a new feature or capability +- **Fixes** — a bug fix +- **Updates** — an enhancement to existing behavior +- **Removes** — removed functionality +- **Refactors** — internal restructuring with no behavior change + +Focus on how the change affects someone **using** the package, not implementation details. The description ends up in the CHANGELOG, which people read once during upgrades. + +**Patch** (bug fixes, refactors, small improvements): + +```markdown +--- +"emdash": patch +--- + +Fixes CLI `--json` flag so JSON output is clean. Log messages now go to stderr when `--json` is set. +``` + +**Minor** (new features, non-breaking additions): + +```markdown +--- +"emdash": minor +--- + +Adds `scheduled_at` field to content entries, enabling scheduled publishing via the admin UI. +``` + +**Major** (breaking changes) — include migration guidance: + +```markdown +--- +"emdash": major +--- + +Removes the `legacyAuth` option from the integration config. All sites must use passkey authentication. + +To migrate, remove `legacyAuth: true` from your `emdash()` config in `astro.config.mjs`. +``` + +### Which packages? + +Only published packages need changesets. Demos, templates, docs, and test fixtures are excluded. The main packages are: + +- `emdash` (core) +- `@emdash-cms/admin`, `@emdash-cms/auth`, `@emdash-cms/cloudflare`, `@emdash-cms/blocks` +- `create-emdash` +- First-party plugins (`@emdash-cms/plugin-*`) + +When in doubt, run `pnpm changeset` and it will only show packages that aren't ignored. + ## Commits and PRs - Branch from `main`.