Make Changes

Make Changes

Overview

Write concise release notes that match this repository's .changes conventions. Use this skill for both new change files and edits to existing unpublished ones.

Workflow

1. Read the package's package.json, existing .changes/ directory if present, and any relevant PR diff or commit range.
2. Read recent released entries from the relevant package changelog on origin/main. Use them as the editorial reference for voice, structure, and level of detail; use unpublished change files to detect overlap and follow placement conventions, not as the sole writing model.
3. Check whether an unpublished change file already exists for the same work. If it does, update it in place instead of creating a duplicate note.
4. Choose the bump type from the package version and the user-facing impact.
5. Create packages/<package>/.changes/ on demand if it does not already exist.
6. Write changelog copy that describes shipped behavior, APIs, exports, migrations, or upgrade work from the user's perspective.
7. Run pnpm changes:preview and review the affected package sections as complete changelog sections, not isolated rendered files. Edit for repetition, inconsistent voice, fragmented migrations, and overlapping notes.
8. Run lint or broader validation when the task also touched code, package metadata, docs, or release tooling.

Bump Rules

• For 0.x packages, use minor for new features and breaking changes, and patch for bug fixes.
• Do not use major for 0.x packages unless explicitly instructed.
• For 1.x+ packages, use standard semver.
• Breaking changes are relative to main, not earlier commits in the same PR.
• In 0.x, breaking change notes must start with BREAKING CHANGE: .
• For remix prerelease mode, the bump type mostly controls changelog categorization while the prerelease counter advances.

Placement And Naming

• Use packages/<package>/.changes/[major|minor|patch].short-description.md.
• Keep the slug short, specific, and stable.
• Reuse existing deterministic names when the repo already has a pattern for that class of note.
• For brand-new package releases, prefer minor.initial-release.md.
• For Remix export-only changes, update packages/remix/.changes/minor.remix.update-exports.md in place.
• When packages/remix/.changes mirrors a change file from a re-exported package, name it packages/remix/.changes/[major|minor|patch].<package>.short-description.md, where <package> omits the @remix-run/ scope.

Note Content

• Treat every change file as final changelog copy, not as a PR summary, implementation log, or inventory of touched APIs.
• Document user-visible behavior, public API changes, exports, migrations, or upgrade work.
• Do not write release notes for internal refactors unless they surface as real API or behavior changes.
• Keep each note self-contained. A reader should understand the shipped behavior from the note itself, with links adding context rather than replacing the explanation.
• Lead with the user-visible behavior, consequence, or required migration in direct language. Introduce API names where they become relevant to that explanation instead of opening with an inventory such as “This adds X, allows Y, and exposes Z.”
• When a change is tied to a public issue, PR, RFC, decision doc, spec, or external bug report, include a short reference in the note. Prefer the PR that actually addressed the issue or feature over the source issue because the source issue remains reachable from the PR. Use inline same-repo references like (see #1234) and full URLs for external repositories, specs, or reports.
• Name the affected API, route convention, package, entrypoint, runtime, browser, or tool version when that detail helps users recognize whether the note applies to them.
• For bug fixes, describe the user-visible symptom or failing scenario instead of only describing the implementation fix.
• Structure breaking changes in this order: state what changed, explain the practical impact or who is affected, then give the migration. Do not bury the required action beneath implementation background.
• For deprecations, mention the replacement API when one exists.
• When migration prose tells readers to change code, configuration, commands, or entrypoints, include a fenced diff that shows that change. Keep enough surrounding context to identify the owning function call, configuration object, command, or entrypoint; avoid context-free fragments containing only the renamed token.
• Use contextual before/after examples for changed behavior when a diff would be misleading or when multiple complete states are clearer. Show the owning function, configuration, or entrypoint in both examples.
• Avoid linking every implementation PR when it does not add useful reader context.
• Prefer a small number of logically grouped notes over many tiny files. Consolidate related cross-package changes when they describe one migration, user workflow, or app-level capability, while keeping the owning package notes complete.
• Do not manually hard-wrap prose in .changes/*.md files. Keep each paragraph or bullet on a single source line and let rendered changelogs wrap naturally.
• Use flat bullets only when they add clarity. Short paragraphs are usually better.
• Do not edit historical CHANGELOG.md entries unless explicitly asked, except for narrow corrections such as broken links, typos, or clearly invalid references.