Versioning Policy
On this page
Fouria is a monorepo containing published packages, private Cloudflare Workers, and an Elixir application. These components serve different audiences and deployment models, so they use two versioning schemes. The monorepo itself has no version.
Version Schemes
1. Semantic Versioning (Semver)
Applies to: semver products managed by Changesets.
MAJOR.MINOR.PATCH e.g. 0.4.0| Component | Version source | Changelog |
|---|---|---|
packages/moltlazy | packages/moltlazy/package.json | packages/moltlazy/CHANGELOG.md |
packages/cost-calculator | packages/cost-calculator/package.json | packages/cost-calculator/CHANGELOG.md |
apps/lerma | apps/lerma/package.json (mirrors mix.exs) | apps/lerma/CHANGELOG.md |
| Bump | When | Examples |
|---|---|---|
| MAJOR | Breaking API or CLI changes | SDK type renames, removed config keys, dropped Node versions |
| MINOR | New features, backward-compatible | New config modules, new SDK methods, new CLI flags |
| PATCH | Bug fixes, docs, internal refactors | Config generation fixes, type corrections, test additions |
Changesets workflow
- Every pull request adds a changeset with
bun run changeset(or a non-interactive form such asbun run changeset --patch moltlazy --message "fix: …"). The changeset records the affected package, the bump type (patch/minor/major), and the changelog summary. A change that must not release anything (docs, CI, tests, IaC, CalVer-only components) commits an empty changeset instead (bun run changeset --empty);changeset versionconsumes it without bumping any package. A PR with no committed changeset is not ready to merge —changeset-statusonly reminds, it does not block. - The Version Packages workflow
(
.github/workflows/version-packages.yml) runs on every push todevelop. It aggregates the pending changesets into one pull request that:- bumps each package’s
version; - writes the new section in each package’s
CHANGELOG.mdusing the custom generator inscripts/changeset-changelog.mjs(commit links included); - runs
scripts/sync-versions.mjssoapps/lerma/mix.exsmatches itspackage.jsonmirror.
- bumps each package’s
- Merging the Version Packages pull request is the entire versioning step. Nobody selects a patch/minor/major level at release time.
One-time repository setting: enable Settings → Actions → General → Allow GitHub Actions to create and approve pull requests so the Changesets action can open the version PR.
No CI on the Version Packages PR. The PR-triggered workflows (
test.yml,lerma.yml,staging-validation-ci.yml,changeset-status.yml) skip thechangeset-release/*head branch the Changesets action opens, because the PR only bumps versions and writes changelogs. Its correctness is checked by theversion-packagesworkflow itself, and the release train fails fast if the merge left pending changesets or drifting versions. If a required status check ever blocks that PR, the checks now report as skipped (not pending), which branch protection accepts.
- The next release train records and tags those versions. Changesets never bumps a semver package again during the release itself.
The .changeset/config.json file lists the CalVer workers under ignore, so a
changeset can never accidentally turn apps/fouria or workers/fouria-dispatch
into semver packages. The custom changelog generator is configured as:
"changelog": ["../scripts/changeset-changelog.mjs", { "repo": "0xCAB0/fouria" }]
Lerma mirror. Changesets can only version
package.jsonfiles. Lerma’s authoritative Elixir version lives inapps/lerma/mix.exs; a small privateapps/lerma/package.jsonmirrors it so Changesets can bump it, andscripts/sync-versions.mjscopies the result back intomix.exs. The release workflow fails if the two files drift (bun run scripts/sync-versions.mjs --check).
2. Date-Based Versioning
Applies to: Cloudflare Workers and deployed apps.
YYYY.M.D e.g. 2026.6.1
For multiple releases on the same day, append a hyphen and counter:
YYYY.M.D-N e.g. 2026.6.1-2Components using date-based versioning
| Component | Path | Version field |
|---|---|---|
| Tenant worker (moltbot-sandbox) | apps/fouria/package.json | version |
| Dispatch worker | workers/fouria-dispatch/package.json | version |
CalVer components are not managed by Changesets. scripts/release.mjs detect
sets them to today’s date when their path changed since their last tag, and the
release train writes the version + git tag.
OpenClaw plugins
OpenClaw plugins are no longer versioned in this monorepo. The
cloudflare-unified-billing plugin and its release train moved to
Paso4/openclaw-plugins, which ships
one global version locked to the OpenClaw release it targets. See
OPENCLAW-PLUGINS.md.
3. Elixir-Native Versioning
Applies to: The Elixir/Phoenix application (apps/lerma).
The version is declared in apps/lerma/mix.exs and follows standard Elixir/Mix
conventions. It is kept in lockstep with the Changesets-managed
apps/lerma/package.json mirror by scripts/sync-versions.mjs; see the semver
section above.
Release Train
Deployed components (workers and apps) follow a release train: on deployment day, all CalVer components that have changed since their last version bump receive today’s date as their version. Unchanged components stay on their prior version. Semver components are released at the version Changesets already calculated.
Release day workflow
- Merge the Version Packages PR. It must contain the semver bumps and
changelogs. The release workflow fails fast if
.changeset/*.mdstill has pending changesets, with a message pointing at the Version Packages workflow. - Trigger the Release workflow (
.github/workflows/release.yml,workflow_dispatch). There are no bump-level inputs. - Detect changed components.
scripts/release.mjs detect:- computes today’s CalVer (
YYYY.M.D, orYYYY.M.D-Nfor a later release on the same day) from the existing tags and root version; - finds CalVer components whose path changed since their last component tag;
- finds semver packages whose current version has no path-scoped tag yet (the Changesets bump is the signal — the release never bumps it again).
- computes today’s CalVer (
- Bump, commit, and tag. The release-it
before:bumphook runsscripts/release.mjs bump, which writes CalVer versions, syncs Lerma’smix.exs, and appends the CalVer changelog entries. release-it then commits the version/changelog changes and creates the GitHub release. Theafter:releasehook runsscripts/release.mjs tag, which creates the per-component tags at the release commit and pushes them. - Deploy. The
releasedevent keeps drivingdeploy-fouria.yml,deploy-dispatch.yml, anddeploy-dashboard.ymlexactly as before.
Git tags
Each component is tagged independently:
packages/moltlazy/v0.4.0
packages/cost-calculator/v0.1.1
apps/lerma/v0.15.2
apps/fouria/2026.6.1
workers/fouria-dispatch/2026.6.1
Tags are created at the commit where the version was bumped. Semver tags include
a v prefix; CalVer tags use the date directly as the suffix.
Rules
- Root version is release metadata. The monorepo
package.jsonversion is the CalVer release number used by release-it; it is not a product version. - One scheme per component. Semver products use Changesets. Everything else (except Elixir, which mirrors its package) uses date-based versions.
- Truly independent semver. Each semver product versions independently based on its own changesets. A bump does not depend on whether workers changed.
- Coupled date components. Workers share a release train. If any worker ships, all changed workers get the same date.
- Plugin versions live outside this repo. The
cloudflare-unified-billingplugin is versioned in Paso4/openclaw-plugins. - Versions live in
package.json(ormix.exsfor Elixir, mirrored byapps/lerma/package.json). No separate version files or constants. - Bump before deploy. Always merge the Version Packages PR before running the release workflow.
- One changeset per releasing PR. Changesets are committed with the change they describe, not added retroactively at release time.
Release Notes
Each GitHub release is titled with today’s CalVer date (vYYYY.M.D). The release
body contains:
- a table of components whose versions were bumped, showing old → new version;
- a Changelogs section for every bumped component.
Semver components reuse the section Changesets wrote in their CHANGELOG.md
(with commit links). CalVer components get a changelog generated from the
conventional commits that touched their path since the previous component tag,
grouped into Features, Bug fixes, Performance, Refactors, Documentation, Tests,
Build, CI, Reverts, Chores, and Other changes. Each component section links to
the full compare diff. The generated entry is also appended to that component’s
CHANGELOG.md (apps/fouria/CHANGELOG.md,
workers/fouria-dispatch/CHANGELOG.md) and committed with the release.
Format
## Bumped components
| Component | Old version | New version |
| ------------------------- | ----------- | ----------- |
| `packages/moltlazy` | `0.4.0` | `0.4.1` |
| `apps/fouria` | `2026.6.1` | `2026.7.14` |
| `workers/fouria-dispatch` | `2026.6.1` | `2026.7.14` |
## Changelogs
### `packages/moltlazy` — v0.4.0 → v0.4.1
#### Patch Changes
- Keep `$include` paths relative (…) ([abc1234](…))
[Full diff](…)
### `apps/fouria` — v2026.6.1 → v2026.7.14
#### Bug fixes
- **gateway:** … ([def5678](…))
Unchanged components do not appear in the release notes.
Release trigger
The Version Packages workflow runs automatically on every push to develop.
The Release workflow remains a manual workflow_dispatch because it creates
the GitHub release that promotes artifacts and deploys production. It has no
moltlazy_bump/cost_calculator_bump/lerma_bump inputs; those values are now
calculated by Changesets.
Same-day releases
If multiple releases occur on the same day, the CalVer version appends a -N
counter:
v2026.7.14 first release
v2026.7.14-2 second release
v2026.7.14-3 third release
The counter is computed from existing root tags and applies to all CalVer components bumped in that release.
Same-day releases are stable, not prereleases — v2026.7.14-2 is the second
release of that day, not a release candidate. Because 2026.7.14-2 is a valid
semver string (with a numeric prerelease identifier), release-it would otherwise
create the GitHub release with prerelease: true. This is corrected in two places:
- The Release workflow (
.release-it.json) clears the flag with anafter:releasehook:gh release edit ${tagName} --prerelease=false. - The deploy workflows (
deploy-fouria.yml,deploy-dispatch.yml,deploy-dashboard.yml) decide “stable” from the tag name (^vYYYY.M.D(-N)?$) in aclassifyjob, not from the GitHub releaseprereleaseflag, and subscribe to thereleasedevent only. Flipping a pre-release to a release also firesreleased, so subscribing toprereleasedas well would promote the same tag twice.
[!NOTE] The GitHub release always uses today’s CalVer date. Its body includes the bumped-version table and the per-component changelogs described above.
Scenario A: Only a bug fix in moltlazy
- The PR adds a
patchchangeset formoltlazy. - The Version Packages PR bumps
moltlazy0.3.0→0.3.1and adds a#### Patch Changesentry to its changelog. - The release train tags
packages/moltlazy/v0.3.1and includes that changelog section in the GitHub release. - All workers are unchanged and stay at their prior date.
Scenario B: New feature in tenant worker + OpenClaw upgrade
openclaw:2026.7.1→2026.6.12(external plugin repo tracks it separately)- Tenant worker:
2026.6.1→2026.6.15(changed, gets today’s date) - Dispatch worker: unchanged (stays at prior)
- Semver packages: unchanged unless their code also changed
Scenario C: Multi-component release day
moltlazy:0.3.1→0.4.0(breaking SDK change; onemajorchangeset)cost-calculator:0.1.0→0.2.0(new helper; oneminorchangeset)apps/lerma:0.15.1→0.15.2(onepatchchangeset;mix.exssynced)- Tenant worker:
2026.6.1→2026.6.15 - Dispatch worker:
1.0.0→2026.6.15