diff --git a/.dev/servers.json b/.dev/servers.json new file mode 100644 index 0000000..e69de29 diff --git a/doc/decisions/001-version-bumping-strategy.md b/doc/decisions/001-version-bumping-strategy.md new file mode 100644 index 0000000..6d90b72 --- /dev/null +++ b/doc/decisions/001-version-bumping-strategy.md @@ -0,0 +1,29 @@ +# 001. Version Bumping Strategy + +Date: 2026-03-01 + +## Status + +Accepted + +## Context + +To ensure a repeatable and consistent release process for new features and fixes, we needed a standardized way to manage version increments before creating artifacts and publishing. Manually tracking versions in `package.json` is error-prone. + +## Decision + +We decided to use the `npm version ` command within the new publishing script. This command atomically updates `package.json` and creates a corresponding git tag, satisfying prerequisites for automated release workflows. + +## Consequences + +- Positive: Versioning is now integrated with git tagging, reducing manual steps. +- Negative: Requires that the branch has a clean working directory before execution. + +## Alternatives Considered + +- Manually updating `package.json` and using `sed`/`edit` to tag: Too brittle and error-prone. +- Relying solely on GitHub actions for versioning: Lacks local development flow verification. + +## Related + +- Planning: .plan/.done/feat/npm-publish-script/plan.md diff --git a/doc/decisions/002-git-tag-pushing-strategy.md b/doc/decisions/002-git-tag-pushing-strategy.md new file mode 100644 index 0000000..99a09d4 --- /dev/null +++ b/doc/decisions/002-git-tag-pushing-strategy.md @@ -0,0 +1,29 @@ +# 002. Git Tag Pushing Strategy + +Date: 2026-03-01 + +## Status + +Accepted + +## Context + +After updating the version and creating a git tag via `npm version`, the tag must be pushed to the remote repository to register the new version externally and allow CI/CD systems to build official releases. + +## Decision + +The publishing script will use `git push --follow-tags` after successfully bumping the version and committing the change. This ensures that any newly created version tags are pushed along with the version commit. + +## Consequences + +- Positive: Tags are published reliably with the version commit. +- Negative: If the version commit fails to push, the tags are orphaned locally. + +## Alternatives Considered + +- Running `git push origin --tags` separately: Causes an extra command execution step and higher chance of race conditions if interleaved with other operations. +- Relying on `npm publish`: `npm publish` only publishes the package, not the tag to Git. + +## Related + +- Planning: .plan/.done/feat/npm-publish-script/plan.md diff --git a/doc/decisions/003-pre-publish-build-and-test-gate.md b/doc/decisions/003-pre-publish-build-and-test-gate.md new file mode 100644 index 0000000..69ff176 --- /dev/null +++ b/doc/decisions/003-pre-publish-build-and-test-gate.md @@ -0,0 +1,29 @@ +# 003. Pre-Publish Build and Test Gate + +Date: 2026-03-01 + +## Status + +Accepted + +## Context + +To maintain code quality and ensure that published NPM packages are functional, any artifact generated must pass the project's standard build and test routines before it is uploaded to the NPM registry. + +## Decision + +The publishing script enforces a mandatory execution of `npm run format:check`, `npm run build` (if applicable, or equivalent TypeScript check), and `npm test`. The publish step (`npm publish`) only proceeds if all preceding checks pass successfully. + +## Consequences + +- Positive: Prevents publishing of broken or improperly formatted code. +- Negative: Increases total time for a successful release cycle. + +## Alternatives Considered + +- Relying on CI/CD only: This would mean local development releases are untrusted. +- Skipping format check: Violates project standards defined in CLAUDE.md. + +## Related + +- Planning: .plan/.done/feat/npm-publish-script/plan.md diff --git a/doc/decisions/README.md b/doc/decisions/README.md index d3555e7..15cd6e1 100644 --- a/doc/decisions/README.md +++ b/doc/decisions/README.md @@ -18,5 +18,8 @@ We use the [Michael Nygard format](https://cognitect.com/blog/2011/11/15/documen ## Index -- [001. Single-file TypeScript CLI Architecture](001-single-file-typescript-cli-architecture.md) -- [002. Vitest Testing Strategy](002-vitest-testing-strategy.md) + + +- [001. Version Bumping Strategy](001-version-bumping-strategy.md) +- [002. Git Tag Pushing Strategy](002-git-tag-pushing-strategy.md) +- [003. Pre-Publish Build and Test Gate](003-pre-publish-build-and-test-gate.md)