Versioning Policy

On this page

Version Schemes
- 1. Semantic Versioning (Semver)
- 2. Date-Based Versioning
- 3. Elixir-Native Versioning
Release Train
- Release day workflow
- Git tags
Rules
Release Notes
- Format
- Release trigger
- Git tags
- Same-day releases
- Scenario A: Only a bug fix in moltlazy
- Scenario B: New feature in tenant worker + openclaw upgrade
- Scenario C: Multi-component release day

Fouria is a monorepo containing published packages, private Cloudflare Workers, OpenClaw plugins, 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: Published npm packages (moltlazy).

MAJOR.MINOR.PATCH   e.g. 0.4.0

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

Each version bump gets a changelog entry in the component’s CHANGELOG.md. Follow the existing format in packages/moltlazy/CHANGELOG.md.

2. Date-Based Versioning

Applies to: Cloudflare Workers, deployed apps, and OpenClaw plugins.

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

Component	Path	Version field
Tenant worker (moltbot-sandbox)	`apps/fouria/package.json`	`version`
Dispatch worker	`workers/fouria-dispatch/package.json`	`version`
Fouria Dashboard	`apps/lerma/package.json`	`version`

OpenClaw plugins

OpenClaw plugins use date-based versioning locked to the openclaw version they target. The plugin version must equal minOpenclawVersion in openclaw.plugin.json.

Component	Path	Current
Cloudflare Unified Billing	`packages/plugins/cloudflare-unified-billing/package.json`	`2026.7.1`

When the openclaw dependency is bumped, the plugin version bumps with it.

3. Elixir-Native Versioning

Applies to: The Elixir/Phoenix application.

Component	Path
Fouria Dashboard (Phoenix)	`apps/lerma/` (managed via `mix.exs`)

Follows standard Elixir/Mix version conventions. Independent from the JS versioning policy.

Release Train

Deployed components (workers, apps, plugins) follow a release train: on deployment day, all components that have changed since their last version bump receive today’s date as their version. Unchanged components stay on their prior version.

Release day workflow

Identify changed components. Compare each component’s current version against the commits since its last tag or version bump.
Bump semver packages. If moltlazy code changed, bump its version per semver rules and add a CHANGELOG entry.
Bump OpenClaw plugins. If openclaw dependency changed, update both the plugin version and minOpenclawVersion.
Bump date-based components. Set all changed workers/apps to today’s date (YYYY.M.D).
Tag and deploy. Each component gets a git tag (see tagging below).

Git tags

Each component is tagged independently:

packages/moltlazy/v0.4.0
apps/fouria/2026.6.1
workers/fouria-dispatch/2026.6.1
packages/plugins/cloudflare-unified-billing/2026.7.1

Tags are created at the commit where the version was bumped.

Rules

No root version. The monorepo package.json stays unversioned.
One scheme per component. Published packages use semver. Everything else (except Elixir) uses date-based. Elixir uses its own conventions.
Truly independent semver. moltlazy versions independently of the deployed workers. Its semver bump does not depend on whether workers changed.
Coupled date components. Workers and apps share a release train. If any worker ships, all changed workers get the same date.
Plugin version = openclaw version. Never diverge. If openclaw is at 2026.6.3, the plugin is at 2026.6.3.
Versions live in package.json (or mix.exs for Elixir). No separate version files or constants.
Bump before deploy. Always bump the version in source before running wrangler deploy or equivalent.

Release Notes

Each GitHub release is titled with today’s CalVer date (vYYYY.M.D). The release body contains only a table of components whose versions were bumped, showing old → new version. No per-PR changelogs, no commit lists, no category grouping.

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` |

Unchanged components do not appear in the release notes.

Release trigger

Releases are triggered automatically on pushes to develop. For semver components (packages/moltlazy and apps/lerma), the bump level (patch, minor, major) must be selected manually via the workflow_dispatch trigger with moltlazy_bump and lerma_bump inputs. On automatic push triggers, semver components are detected but their versions are not bumped — only CalVer components receive automatic version bumps.

Git tags

Each bumped component receives a per-component git tag:

packages/moltlazy/v0.4.1
apps/fouria/2026.7.14
workers/fouria-dispatch/2026.7.14
packages/plugins/cloudflare-unified-billing/2026.6.12
apps/lerma/v0.1.1

CalVer components use the date directly as the tag suffix (e.g. apps/fouria/2026.7.14). Semver components include a v prefix (e.g. packages/moltlazy/v0.4.1, apps/lerma/v0.1.1).

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.

[!NOTE] Github release always today date (CalVer), on release notes, it must appear only the bumped versions

Scenario A: Only a bug fix in moltlazy

moltlazy: 0.3.0 → 0.3.1 (PATCH bump)
All workers: unchanged, stay at prior date
Plugin: unchanged

Scenario B: New feature in tenant worker + openclaw upgrade

openclaw: 2026.7.1 → 2026.6.12
Plugin: 2026.7.1 → 2026.6.12 (locked to openclaw)
Tenant worker: 1.0.0 → 2026.6.1 (changed, gets today’s date)
Dispatch worker: unchanged (stays at prior)
Outbound worker: unchanged (stays at prior)
moltlazy: unchanged (no semver bump needed)

Scenario C: Multi-component release day

moltlazy: 0.3.1 → 0.4.0 (breaking SDK change)
Tenant worker: 2026.6.1 → 2026.6.15
Dispatch worker: 1.0.0 → 2026.6.15
Outbound worker: 1.0.0 → 2026.6.15
Plugin: unchanged (openclaw not bumped)