Add changelog and release workflow for npm publishing

.github/workflows/release-on-main.yml

@@ -0,0 +1,38 @@
+name: Release On Main
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+concurrency:
+  group: release-on-main
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Release (changelog-driven)
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: ./scripts/release.sh

.release-it.json

@@ -0,0 +1,20 @@
+{
+  "git": {
+    "requireCleanWorkingDir": true,
+    "requireBranch": "main",
+    "tagName": "v${version}",
+    "commitMessage": "chore(release): v${version} [skip ci]",
+    "commit": true,
+    "tag": true,
+    "push": true
+  },
+  "npm": {
+    "publish": true
+  },
+  "github": {
+    "release": true
+  },
+  "hooks": {
+    "before:init": "if [ \"$SKIP_RELEASE_TESTS\" = \"true\" ]; then echo 'Skipping tests/build via SKIP_RELEASE_TESTS'; else npm test && npm run build; fi"
+  }
+}

CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on Keep a Changelog and this project follows Semantic Versioning.
+
+## [Unreleased]
+
+### Added
+
+- _No unreleased changes yet._
+
+## [v1.0.0] - 2026-03-14
+
+### Added
+
+- Initial standalone extraction of the semantic webpack/rspack configuration diff engine from Shakapacker.
+- CLI package and binstub: `pack-config-diff`.
+- Deep diff engine with support for:
+  - objects and arrays
+  - functions, `RegExp`, and `Date`
+  - class-instance-aware behavior for plugin-like objects
+  - ignore keys/paths, max depth, and path separator options
+- Cross-platform path normalization and base-path detection.
+- Rich output formatter support:
+  - `detailed`
+  - `summary`
+  - `json`
+  - `yaml`
+  - `markdown`
+- Contextual documentation mapping for common webpack/rspack config keys.
+- Comprehensive test suite ported from Shakapacker plus integration coverage.
+
+### Improved
+
+- Plugin-aware comparison mode for class-instance configs (`--plugin-aware`).
+- Module rule matching by `rule.test` to reduce reorder noise (`--match-rules-by-test`).
+- Markdown table output with escaping and deterministic entry sorting.
+
+### Build
+
+- Added `prepare` script so installs from GitHub build `dist/` automatically.

README.md

@@ -187,6 +187,16 @@ npm test
 
 Test suites are ported from Shakapacker's `test/configDiffer` and run against this extracted package.
 
+## Release
+
+- Changelog: [`CHANGELOG.md`](./CHANGELOG.md)
+- Maintainer release guide: [`docs/releasing.md`](./docs/releasing.md)
+- Prerelease protocol: [`docs/releasing.md#prerelease-protocol`](./docs/releasing.md#prerelease-protocol)
+- Update changelog via `/update-changelog`, then merge/push to `main`
+- Release automation workflow: `.github/workflows/release-on-main.yml`
+- Release engine config: `.release-it.json`
+- Local dry run: `npm run release:dry-run`
+
 ## License
 
 MIT

docs/releasing.md

@@ -0,0 +1,91 @@
+# Releasing `pack-config-diff`
+
+This repository uses a changelog-driven release flow modeled after Shakapacker:
+
+- You update `CHANGELOG.md` via `/update-changelog`.
+- You commit and push to `main`.
+- CI runs the release script (powered by `release-it`), bumps `package.json`, publishes npm, tags, and creates the GitHub release.
+
+## Prerequisites
+
+1. Repository has `NPM_TOKEN` configured in GitHub Actions secrets.
+2. Repository has `GITHUB_TOKEN` available to the workflow (default Actions token is used).
+3. Maintainer has permissions to merge to `main`.
+4. You have `/update-changelog` available in your workflow.
+
+## Stable Release Protocol
+
+1. Ensure release-ready PRs are merged.
+2. Run:
+
+   ```text
+   /update-changelog release
+   ```
+
+3. Review `CHANGELOG.md` for the new top version header (for example `## [v1.2.3] - YYYY-MM-DD`).
+4. Commit and push only changelog/documentation changes.
+5. Merge/push to `main`.
+
+That push triggers `.github/workflows/release-on-main.yml`, which executes `./scripts/release.sh` and will:
+
+1. Read target version from the top changelog version header.
+2. Bump `package.json` (and `package-lock.json`) to that version.
+3. Run tests/build.
+4. Commit/push the version bump to `main`.
+5. Publish to npm (`latest` for stable).
+6. Create/push tag `vX.Y.Z`.
+7. Create GitHub release via `release-it`.
+
+Release behavior is configured in:
+
+- `.release-it.json`
+- `scripts/release.sh`
+
+## Prerelease Protocol (`rc` / `beta`)
+
+### Rules
+
+- Do not manually edit `package.json` version for release prep.
+- Use `/update-changelog rc` or `/update-changelog beta` to produce prerelease headers.
+- Prerelease versions must use npm semver prerelease format:
+  - `1.2.3-rc.0`
+  - `1.2.3-beta.0`
+
+### Steps
+
+1. Run:
+
+   ```text
+   /update-changelog rc
+   ```
+
+   or
+
+   ```text
+   /update-changelog beta
+   ```
+
+2. Confirm top changelog header is prerelease, e.g. `## [v1.2.3-rc.0] - YYYY-MM-DD`.
+3. Commit and push changelog changes.
+4. Merge/push to `main`.
+
+Release automation will detect prerelease version and publish to npm dist-tag `next` automatically.
+
+## Dry Run / Local Verification (Optional)
+
+You can validate locally without publishing:
+
+```bash
+npm run release:dry-run
+```
+
+This checks branch, changelog/version state, and test/build readiness, and prints planned release actions.
+
+## Post-Release Checks
+
+1. npm package version/dist-tag:
+   - <https://www.npmjs.com/package/pack-config-diff>
+2. Git tag exists:
+   - `vX.Y.Z`
+3. GitHub release exists:
+   - <https://github.com/shakacode/pack-config-diff/releases>