Versioning & Releases
Relevant source files
The following files were used as context for generating this wiki page:
- README.md
- CONTRIBUTING.md
- package.json
- packages/analytics/CHANGELOG.md
- packages/auth/CHANGELOG.md
- packages/config/CHANGELOG.md
- packages/db/CHANGELOG.md
- packages/errors/CHANGELOG.md
- packages/eslint-config/CHANGELOG.md
- packages/jobs/CHANGELOG.md
- packages/storage/CHANGELOG.md
- packages/tsconfig/CHANGELOG.md
The wrelik-kit repository employs a structured, automated approach to versioning and publishing shared packages. By utilizing a monorepo structure managed with pnpm and turbo, the project ensures that vendor-agnostic adapters and shared utilities are released with high discipline and technical accuracy.
Sources: README.md:1-5, package.json:4-18
Versioning Mechanism
The project utilizes Changesets for managing version bumps and generating changelogs. This tool ensures that every change to a package is explicitly documented before being merged into the main branch. Changesets facilitate Semantic Versioning (SemVer) by prompting developers to choose between patch, minor, or major updates based on the impact of their changes.
Sources: CONTRIBUTING.md:23-32, README.md:88-92
The Changeset Workflow
When a developer modifies a package, they must generate a changeset file. This file acts as a precursor to the actual version bump, describing the change and the required SemVer increment.
The flow above illustrates the mandatory manual step in the development process to ensure versioning intent is captured early.
Sources: CONTRIBUTING.md:27-32
Release Lifecycle
The release process is divided into distinct stages, transitioning from local development to automated CI/CD actions that handle the final publishing to the NPM registry.
| Stage | Action | Responsibility |
|---|---|---|
| Development | Create feature branch and implement changes | Developer |
| Versioning | Run pnpm changeset to create intent file | Developer |
| Pull Request | Submit code and changeset for review | Developer |
| Merge | Integrate into main branch after CI passes | Maintainer |
| Version PR | Automatically create "Version Packages" PR | Release GitHub Action |
| Publish | Merge "Version Packages" PR to trigger NPM release | Maintainer |
Sources: CONTRIBUTING.md:34-40
Automated Release Flow
The project leverages a "Release" GitHub Action to automate the transition from merged changes to published artifacts.
This sequence ensures that versions are not bumped manually in package.json files, but rather through a controlled automated process.
Sources: CONTRIBUTING.md:34-40, package.json:15-17
Release Scripts
The root package.json defines the core commands used by both developers and the automated CI environment to manage the lifecycle of the packages.
| Script | Command | Purpose |
|---|---|---|
changeset | changeset | Triggers the CLI to create a new changeset file. |
version | changeset version | Consumes changesets to update package.json versions and CHANGELOGs. |
publish | changeset publish | Publishes the built packages to the package registry. |
Sources: package.json:15-17
Changelog Management
Every package within the packages/ directory maintains its own CHANGELOG.md. These files are automatically updated during the "Version" phase of the release lifecycle. Historically, the project began with an initial release (0.1.0) and transitioned through patch updates (0.1.1) to synchronize configuration changes across the suite.
Example Evolution
- 0.1.0: Initial release of all
wrelik-kitpackages. - 0.1.1: Patch changes, such as updating
publishConfigtoaccess: public.
Sources: packages/config/CHANGELOG.md:1-12, packages/auth/CHANGELOG.md:1-15, packages/db/CHANGELOG.md:1-15
Governance & Constraints
Release discipline is enforced through the following rules:
- Mandatory Changesets: Any change to a package requires a changeset; without it, the release automation will not trigger for that package.
- Explicit Breaking Changes: Documentation of breaking changes is required within the changeset description.
- Infrastructure Treatment: Because the repo is treated as infrastructure, apps consuming these packages are responsible for testing upgrades before full rollout.
- Public Access: All packages are configured with
publishConfig: { "access": "public" }to ensure they are available to the Wrelik ecosystem.
Sources: README.md:90-92, README.md:9-11, packages/auth/package.json:4-6
The versioning and release system of wrelik-kit is designed for stability and predictability, ensuring that the integration boundary between applications and third-party vendors remains robust and well-documented.