Use .changes directories to drive releases

.github/workflows/typecheck.yaml → .github/workflows/check.yaml

@@ -9,7 +9,7 @@ on:
       - v2
 
 jobs:
-  typecheck:
+  check:
     runs-on: ubuntu-latest
 
     steps:
@@ -28,5 +28,9 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      - name: Check change files
+        run: pnpm changes:validate
+
       - name: Run typechecks
         run: pnpm typecheck
+

AGENTS.md

@@ -37,7 +37,14 @@
 - **Accessible navigation**: Always use proper `<a>` elements for navigation links. Never use JavaScript `onclick` handlers on non-interactive elements like `<tr>`, `<div>`, or `<span>` for navigation. Links should be keyboard accessible and work with screen readers.
 - **Clean shutdown**: Demo servers should handle `SIGINT` and `SIGTERM` signals to exit cleanly when Ctrl+C is pressed. Close the server and call `process.exit(0)`.
 
-## Changelog Formatting
-
-- Use `## Unreleased` as the heading for unreleased changes (not `## HEAD`)
-- Scripts in `./scripts` are configured to replace `## Unreleased` with version and date on release
+## Changes and Releases
+
+- **Adding changes**: Create `packages/*/.changes/[major|minor|patch].short-description.md` files. See [CONTRIBUTING.md](./CONTRIBUTING.md#adding-a-change-file) for details.
+- **Updating changes**: If iterating on an unpublished change with a change file, update it in place rather than creating a new one.
+- **Versioning**: Follow semver 0.x.x conventions where breaking changes can happen in minor releases:
+  - For **v0.x.x packages**: Use "minor" for breaking changes and new features, "patch" for bug fixes. Never use "major" unless explicitly instructed.
+  - For **v1.x.x+ packages**: Use standard semver - "major" for breaking changes, "minor" for new features, "patch" for bug fixes.
+  - **Breaking changes are relative to main**: If you introduce a new API in a PR and then change it within the same PR before merging, that's not considered a breaking change.
+- **Validating changes**: `pnpm changes:validate` checks that all change files follow the correct naming convention and format.
+- **Previewing releases**: `pnpm changes:preview` shows which packages will be released, what the CHANGELOG will look like, the commit message and tags.
+- **Versioning releases**: `pnpm changes:version` updates package.json, CHANGELOG.md, creates a git commit and tags. Don't run this unless explicitly instructed to do so. We don't want accidental releases during development.

CONTRIBUTING.md

@@ -38,32 +38,109 @@ All packages are published with TypeScript types along with both ESM and CJS mod
 
 Packages live in the [`packages` directory](https://github.com/remix-run/remix/tree/v3/packages). At a minimum, each package includes:
 
+- `.changes/`: Directory containing change files for the next release
 - `CHANGELOG.md`: A log of what's changed
 - `package.json`: Package metadata and dependencies
 - `README.md`: Information about the package
 - `src/`: The package's source code
 
-When you make changes to a package, please make sure you add a few relevant tests and run the whole test suite to make sure everything still works. Then, add a human-friendly description of your change in the changelog and [make a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). We will take a look at it as soon as we can.
+When you make changes to a package, please make sure you add a few relevant tests and run the whole test suite to make sure everything still works. Then, [add a change file](#adding-a-change-file) describing your changes and [make a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). We will take a look at it as soon as we can.
+
+### Adding a Change File
+
+When making changes to a package, create a markdown file in the package's `.changes/` directory following this naming convention:
+
+```
+[major|minor|patch].short-description.md
+```
+
+#### Examples
+
+- `major.breaking-api-change.md` - Breaking change requiring major version bump
+- `minor.add-new-feature.md` - New feature requiring minor version bump
+- `patch.fix-bug.md` - Bug fix requiring patch version bump
+
+#### Content Format
+
+Write your change as a bullet point (without the leading `-` or `*`). This content will be added to the CHANGELOG during release.
+
+**Simple change:**
+
+```markdown
+Add support for X feature
+```
+
+**Multi-line change:**
+
+```markdown
+Add support for X feature
+
+This is a longer explanation that will be indented
+under the main bullet point in the CHANGELOG.
+```
+
+#### Validation
+
+Change files are automatically validated in CI. You can also validate them locally:
+
+```sh
+pnpm changes:validate
+```
 
 ## Releases
 
-Cutting releases is a 2-step process:
+Cutting releases is a multi-step process:
+
+1. **Preview** - See what will be released
+2. **Version** - Update versions and create commit/tags locally
+3. **Push** - Push to GitHub (triggers CI to publish to npm)
+
+### Preview a Release
+
+To see which packages have changes and preview the release:
+
+```sh
+pnpm changes:preview
+```
+
+This shows:
 
-- Update versions in package.json and the changelog and create a git tag (tagging)
-- Publish new packages to npm and create a GitHub Release (publishing)
+- Which packages will be released with version bumps
+- CHANGELOG additions
+- Git tags that will be created
+- Commit message
 
-This repo includes a script for each step.
+### Version a Release
 
-To update versions and create a tag, use `pnpm run tag-release <packageName> <releaseType>`. For example, to create a `minor` release of the `headers` package, run:
+When ready to release, update versions and create the commit and tags locally:
 
 ```sh
-pnpm run tag-release headers minor
+pnpm changes:version
 ```
 
-To publish the release you just tagged, use `pnpm run publish-release <tag>`. For example, if the tag that was created in the previous step was `[email protected]`, you'd run `pnpm run publish-release [email protected]`.
+This will:
+
+- Validate all change files
+- Update `package.json` versions
+- Update `CHANGELOG.md` files
+- Delete processed change files
+- Create a git commit
+- Create git tags
 
-The publish step runs in GitHub Actions if you just push the tag to GitHub:
+If you want to review the file changes before committing:
 
 ```sh
-git push origin main --tags
+pnpm changes:version --no-commit
 ```
+
+This updates the files but skips git operations. After reviewing, the script will show you the exact git commands to run to create the commit and tags.
+
+### Push the Release
+
+Push the release commit and tags to GitHub:
+
+```sh
+git push && git push --tags
+```
+
+GitHub Actions will automatically publish the tagged packages to npm and create GitHub Releases.

package.json

@@ -17,15 +17,16 @@
   },
   "scripts": {
     "build": "pnpm -r build",
+    "changes:preview": "node ./scripts/changes-preview.js",
+    "changes:validate": "node ./scripts/changes-validate.js",
+    "changes:version": "node ./scripts/changes-version.js",
     "clean": "git clean -fdX -e '!/.env' .",
     "codegen": "pnpm -r run codegen",
     "create-github-release": "node --env-file .env ./scripts/create-github-release.js",
     "lint": "eslint . --max-warnings=0",
     "lint:fix": "eslint . --fix",
-    "tag-release": "node ./scripts/tag-release.js",
     "test": "pnpm --parallel run test",
-    "typecheck": "pnpm -r typecheck",
-    "view-changes": "node ./scripts/view-changes.js"
+    "typecheck": "pnpm -r typecheck"
   },
   "workspaces": [
     "packages/*"

packages/async-context-middleware/.changes/README.md

@@ -0,0 +1,23 @@
+# Changes Directory
+
+This directory contains change files that will be processed during releases.
+
+## Adding a Change
+
+See the [Contributing Guide](../../../CONTRIBUTING.md#adding-a-change-file) for documentation on how to add change files.
+
+## Quick Reference
+
+Create a file with the pattern:
+
+```
+[major|minor|patch].short-description.md
+```
+
+Examples:
+
+- `major.breaking-api-change.md`
+- `minor.add-new-feature.md`
+- `patch.fix-bug.md`
+
+The content will be added to the CHANGELOG during release.

packages/compression-middleware/.changes/README.md

@@ -0,0 +1,23 @@
+# Changes Directory
+
+This directory contains change files that will be processed during releases.
+
+## Adding a Change
+
+See the [Contributing Guide](../../../CONTRIBUTING.md#adding-a-change-file) for documentation on how to add change files.
+
+## Quick Reference
+
+Create a file with the pattern:
+
+```
+[major|minor|patch].short-description.md
+```
+
+Examples:
+
+- `major.breaking-api-change.md`
+- `minor.add-new-feature.md`
+- `patch.fix-bug.md`
+
+The content will be added to the CHANGELOG during release.

packages/cookie/.changes/README.md

@@ -0,0 +1,23 @@
+# Changes Directory
+
+This directory contains change files that will be processed during releases.
+
+## Adding a Change
+
+See the [Contributing Guide](../../../CONTRIBUTING.md#adding-a-change-file) for documentation on how to add change files.
+
+## Quick Reference
+
+Create a file with the pattern:
+
+```
+[major|minor|patch].short-description.md
+```
+
+Examples:
+
+- `major.breaking-api-change.md`
+- `minor.add-new-feature.md`
+- `patch.fix-bug.md`
+
+The content will be added to the CHANGELOG during release.

packages/fetch-proxy/.changes/README.md

@@ -0,0 +1,23 @@
+# Changes Directory
+
+This directory contains change files that will be processed during releases.
+
+## Adding a Change
+
+See the [Contributing Guide](../../../CONTRIBUTING.md#adding-a-change-file) for documentation on how to add change files.
+
+## Quick Reference
+
+Create a file with the pattern:
+
+```
+[major|minor|patch].short-description.md
+```
+
+Examples:
+
+- `major.breaking-api-change.md`
+- `minor.add-new-feature.md`
+- `patch.fix-bug.md`
+
+The content will be added to the CHANGELOG during release.

packages/fetch-router/.changes/README.md

@@ -0,0 +1,23 @@
+# Changes Directory
+
+This directory contains change files that will be processed during releases.
+
+## Adding a Change
+
+See the [Contributing Guide](../../../CONTRIBUTING.md#adding-a-change-file) for documentation on how to add change files.
+
+## Quick Reference
+
+Create a file with the pattern:
+
+```
+[major|minor|patch].short-description.md
+```
+
+Examples:
+
+- `major.breaking-api-change.md`
+- `minor.add-new-feature.md`
+- `patch.fix-bug.md`
+
+The content will be added to the CHANGELOG during release.

packages/file-storage/.changes/README.md

@@ -0,0 +1,23 @@
+# Changes Directory
+
+This directory contains change files that will be processed during releases.
+
+## Adding a Change
+
+See the [Contributing Guide](../../../CONTRIBUTING.md#adding-a-change-file) for documentation on how to add change files.
+
+## Quick Reference
+
+Create a file with the pattern:
+
+```
+[major|minor|patch].short-description.md
+```
+
+Examples:
+
+- `major.breaking-api-change.md`
+- `minor.add-new-feature.md`
+- `patch.fix-bug.md`
+
+The content will be added to the CHANGELOG during release.

packages/form-data-middleware/.changes/README.md

@@ -0,0 +1,23 @@
+# Changes Directory
+
+This directory contains change files that will be processed during releases.
+
+## Adding a Change
+
+See the [Contributing Guide](../../../CONTRIBUTING.md#adding-a-change-file) for documentation on how to add change files.
+
+## Quick Reference
+
+Create a file with the pattern:
+
+```
+[major|minor|patch].short-description.md
+```
+
+Examples:
+
+- `major.breaking-api-change.md`
+- `minor.add-new-feature.md`
+- `patch.fix-bug.md`
+
+The content will be added to the CHANGELOG during release.

packages/form-data-parser/.changes/README.md

@@ -0,0 +1,23 @@
+# Changes Directory
+
+This directory contains change files that will be processed during releases.
+
+## Adding a Change
+
+See the [Contributing Guide](../../../CONTRIBUTING.md#adding-a-change-file) for documentation on how to add change files.
+
+## Quick Reference
+
+Create a file with the pattern:
+
+```
+[major|minor|patch].short-description.md
+```
+
+Examples:
+
+- `major.breaking-api-change.md`
+- `minor.add-new-feature.md`
+- `patch.fix-bug.md`
+
+The content will be added to the CHANGELOG during release.

packages/fs/.changes/README.md

@@ -0,0 +1,23 @@
+# Changes Directory
+
+This directory contains change files that will be processed during releases.
+
+## Adding a Change
+
+See the [Contributing Guide](../../../CONTRIBUTING.md#adding-a-change-file) for documentation on how to add change files.
+
+## Quick Reference
+
+Create a file with the pattern:
+
+```
+[major|minor|patch].short-description.md
+```
+
+Examples:
+
+- `major.breaking-api-change.md`
+- `minor.add-new-feature.md`
+- `patch.fix-bug.md`
+
+The content will be added to the CHANGELOG during release.