F FourIA staging 2026.10.29 GitHub ↗

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
ComponentVersion sourceChangelog
packages/moltlazypackages/moltlazy/package.jsonpackages/moltlazy/CHANGELOG.md
packages/cost-calculatorpackages/cost-calculator/package.jsonpackages/cost-calculator/CHANGELOG.md
apps/lermaapps/lerma/package.json (mirrors mix.exs)apps/lerma/CHANGELOG.md
BumpWhenExamples
MAJORBreaking API or CLI changesSDK type renames, removed config keys, dropped Node versions
MINORNew features, backward-compatibleNew config modules, new SDK methods, new CLI flags
PATCHBug fixes, docs, internal refactorsConfig generation fixes, type corrections, test additions

Changesets workflow

  1. Every pull request adds a changeset with bun run changeset (or a non-interactive form such as bun 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 version consumes it without bumping any package. A PR with no committed changeset is not ready to merge — changeset-status only reminds, it does not block.
  2. The Version Packages workflow (.github/workflows/version-packages.yml) runs on every push to develop. It aggregates the pending changesets into one pull request that:
    • bumps each package’s version;
    • writes the new section in each package’s CHANGELOG.md using the custom generator in scripts/changeset-changelog.mjs (commit links included);
    • runs scripts/sync-versions.mjs so apps/lerma/mix.exs matches its package.json mirror.
  3. 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 the changeset-release/* head branch the Changesets action opens, because the PR only bumps versions and writes changelogs. Its correctness is checked by the version-packages workflow 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.

  1. 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.json files. Lerma’s authoritative Elixir version lives in apps/lerma/mix.exs; a small private apps/lerma/package.json mirrors it so Changesets can bump it, and scripts/sync-versions.mjs copies the result back into mix.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-2

Components using date-based versioning

ComponentPathVersion field
Tenant worker (moltbot-sandbox)apps/fouria/package.jsonversion
Dispatch workerworkers/fouria-dispatch/package.jsonversion

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

  1. Merge the Version Packages PR. It must contain the semver bumps and changelogs. The release workflow fails fast if .changeset/*.md still has pending changesets, with a message pointing at the Version Packages workflow.
  2. Trigger the Release workflow (.github/workflows/release.yml, workflow_dispatch). There are no bump-level inputs.
  3. Detect changed components. scripts/release.mjs detect:
    • computes today’s CalVer (YYYY.M.D, or YYYY.M.D-N for 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).
  4. Bump, commit, and tag. The release-it before:bump hook runs scripts/release.mjs bump, which writes CalVer versions, syncs Lerma’s mix.exs, and appends the CalVer changelog entries. release-it then commits the version/changelog changes and creates the GitHub release. The after:release hook runs scripts/release.mjs tag, which creates the per-component tags at the release commit and pushes them.
  5. Deploy. The released event keeps driving deploy-fouria.yml, deploy-dispatch.yml, and deploy-dashboard.yml exactly 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

  1. Root version is release metadata. The monorepo package.json version is the CalVer release number used by release-it; it is not a product version.
  2. One scheme per component. Semver products use Changesets. Everything else (except Elixir, which mirrors its package) uses date-based versions.
  3. Truly independent semver. Each semver product versions independently based on its own changesets. A bump does not depend on whether workers changed.
  4. Coupled date components. Workers share a release train. If any worker ships, all changed workers get the same date.
  5. Plugin versions live outside this repo. The cloudflare-unified-billing plugin is versioned in Paso4/openclaw-plugins.
  6. Versions live in package.json (or mix.exs for Elixir, mirrored by apps/lerma/package.json). No separate version files or constants.
  7. Bump before deploy. Always merge the Version Packages PR before running the release workflow.
  8. One changeset per releasing PR. Changesets are committed with the change they describe, not added retroactively at release time.
  9. Change history lives in the product changelog. Each product’s CHANGELOG.md is its only change log; AGENTS.md files are operating guidance, not changelogs. The hand-maintained history that used to sit in apps/fouria/AGENTS.md was imported verbatim into the owning product changelogs under ## Historical changes (one-time exception to the no-hand-editing rule above). Do not re-add a changelog to an AGENTS.md.

Release Notes

Each GitHub release is titled with today’s CalVer date (vYYYY.M.D). The release body contains:

  1. a table of components whose versions were bumped, showing old → new version;
  2. 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 an after:release hook: 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 a classify job, not from the GitHub release prerelease flag, and subscribe to the released event only. Flipping a pre-release to a release also fires released, so subscribing to prereleased as 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.

Documentation channels

The platform docs site is versioned by the same release train. It is published in two channels so instances can read release notes that are factually compatible with the code they run:

ChannelSourceURL
latestnewest v* release tag/latest/ (the root aliases /)
stagingdevelop head/staging/

latest is built from the release tag’s checkout (never from develop), and the production deployment also carries /staging/ so it never lags the staging platform. Each channel publishes versions.json (channel, commit, component versions) and release-notes/ compiled from the component CHANGELOG.md files; a channel’s notes therefore only list what exists in that channel’s code. The Worker forwards the channel and its docs URLs to each container (FOURIA_DOCS_CHANNEL, FOURIA_DOCS_BASE_URL, FOURIA_DOCS_FALLBACK_URL). See webs/fouria-docs/README.md.

Scenario A: Only a bug fix in moltlazy

  1. The PR adds a patch changeset for moltlazy.
  2. The Version Packages PR bumps moltlazy 0.3.0 → 0.3.1 and adds a #### Patch Changes entry to its changelog.
  3. The release train tags packages/moltlazy/v0.3.1 and includes that changelog section in the GitHub release.
  4. 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; one major changeset)
  • cost-calculator: 0.1.0 → 0.2.0 (new helper; one minor changeset)
  • apps/lerma: 0.15.1 → 0.15.2 (one patch changeset; mix.exs synced)
  • Tenant worker: 2026.6.1 → 2026.6.15
  • Dispatch worker: 1.0.0 → 2026.6.15