# Versioning Policy

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](https://changesets.dev/).

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

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.

4. 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:

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

| 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](https://github.com/Paso4/openclaw-plugins), which ships
one global version locked to the OpenClaw release it targets. See
[OPENCLAW-PLUGINS.md](/staging/llms/platform/libraries/openclaw-plugins/index.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](https://github.com/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:

| Channel   | Source                  | URL                               |
| --------- | ----------------------- | --------------------------------- |
| `latest`  | newest `v*` release tag | `/latest/` (the root aliases `/`) |
| `staging` | `develop` 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](https://github.com/0xCAB0/fouria/blob/develop/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`
