# Versioning & Support

> How Strutvane's version numbers work, how long each line gets fixes, which branch and npm dist-tag each line uses, how the core packages and add-ons are versioned, and how deprecations work.

Source: https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/versioning/

This page is the rulebook for Strutvane's versions: what a version number promises, how long each version gets fixes, where each version lives (its git branch, its npm dist-tag and its docs), and how something is deprecated before it's removed. The two tables below are generated from **one file**, `versions.json`, every time these docs are built, so they're the same in every version of the docs.

> **Coming from Laravel?**
> It's Laravel's model. Semantic versioning, one version number for the framework's core packages, a yearly major from 1.0 with **18 months of bug fixes and 2 years of security fixes**, a permanent branch per line (`12.x` → our `0.2.x`), and docs per line at `/docs/<line>/`. Two Strutvane additions: before 1.0 each `0.N` line plays the role of a major, and add-on packages (like Laravel's Horizon or Cashier) have their own version numbers.

> **Proposed, and Coming in 0.2**
> This policy is written in ADR-0020, which is **proposed and waiting for the project lead's approval**. Blueprint 18 §3.3 (decided on 2026-11-15) already refines it for add-ons. Nothing is released yet, so no line has a release date and no dist-tag below exists on npm yet. The docs side (one build per branch, the version switcher, the banners and these tables) is built in this docs site's prototype.

## The smallest example

You create an app on the current line and keep it on that line:

```bash
npm create strutvane@latest my-app
```

**What you'll see** in the new app's `package.json` (something like this; the exact numbers depend on the release):

```json title="package.json"
{
  "dependencies": {
    "@strutvane/framework": "^0.2.0",
    "@strutvane/auth": "^0.2.0",
    "@strutvane/ui": "^0.2.0",
    "@strutvane/design-crisp": "^0.2.0"
  }
}
```

`^0.2.0` means "any 0.2 release from 0.2.0 on", and never 0.3. So `npm update` always stays safe: it only moves you to releases that promise not to break your app.

## What a version number promises

A **version line** is a family of releases that never break each other: 0.2.0, 0.2.1 and 0.2.2 are all the 0.2 line.

**Before 1.0:**

- A **new line** (`0.2 → 0.3`) **may contain breaking changes**. Each one is listed in the [upgrade guide](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/upgrade/), with how likely it is to affect you.
- **Releases within a line** (`0.2.3 → 0.2.4`) **never break your app**. They carry bug fixes and backward-compatible features.
- A new line ships at most once every three months.

**From 1.0:**

- **One major release a year** (around Q1). Only majors may break.
- **Minor and patch releases** can ship as often as every week and never break.

### What counts as public API

The promise covers:

- everything a package exports;
- `node strut` commands and flags;
- installer questions and flags;
- config files and `.env` keys;
- the migration Schema builder;
- the shape of generated files (`.strutvane/*`, `resources.json`, `ui.gen.ts`);
- the HTTP conventions of the generated API (query parameters, error `code`s, the pagination envelope);
- the tables the framework owns.

Code that Strutvane generates into your app counts too. If a release would make an app generated by an earlier release of the same line stop compiling or behave differently, that's a bug.

**Not covered** (these may change in any release):

- imports from `internal` paths, or anything marked `@internal`;
- the wording of log lines, error `detail` text and human-readable CLI output (use `--json` in scripts);
- the exact SQL the ORM generates;
- the order of keys in generated JSON;
- the HTML of developer pages under `/_strutvane/`.

## How long each line gets fixes

**Before 1.0:**

- The **newest** 0.x line gets bug fixes and security fixes.
- When the next line ships, the previous one gets **security fixes for 6 more months**, then reaches **end of life** (no fixes at all).

**From 1.0:** every major gets **bug fixes for 18 months** and **security fixes for 2 years** from its release.

| Version | Node | Release | Bug fixes until | Security fixes until | Status |
|---|---|---|---|---|---|
| **0.2** (you are reading these docs) | 24.3+ | Not released yet | Release of the next line | Next line’s release + 6 months | Bug and security fixes |
| 0.1 | 24+ | Pre-releases only | — | — | End of life |

**What a "bug fix" and a "security fix" are:**

- A **security fix** fixes a vulnerability published as a GitHub Security Advisory.
- A **bug fix** fixes anything that doesn't work as these docs describe.
- In a security-only line we may also fix critical bugs, such as data loss or a broken upgrade path, but we don't promise to.

## Lines, branches and dist-tags

Each released line gets a **permanent branch** named after it (`0.2.x`, later `1.x`), created from its first release. `main` holds the next line. An **npm dist-tag** is a name npm uses to pick a version when you don't give one: `npm install x` installs whatever the `latest` tag points at.

| Line | Branch | npm dist-tag | Create an app | Docs | Node | Status |
|---|---|---|---|---|---|---|
| 0.2 | `0.2.x` | `latest` | `npm create strutvane@latest my-app` | `/docs/0.2.x/` | 24.3+ | Bug and security fixes |
| 0.1 | `0.1.x` | `next` | `npm create strutvane@0.1 my-app -- --allow-eol` | `/docs/0.1.x/` | 24+ | End of life |

| Dist-tag | What it points at |
|---|---|
| `latest` | the newest release of the current line |
| `latest-0.2`, `latest-1`, … | the newest release of an older line that still gets fixes |
| `next` | previews of the next line, built from `main` (not for production) |

**Where a fix goes:**

| Change | Goes to |
|---|---|
| Bug fix | the oldest line in its bug-fix window that has the bug, then merged up into every newer line and `main` |
| Security fix | the oldest line in its security window, then merged up |
| Backward-compatible feature | the current line |
| Breaking change | `main` (the next line) |

End-of-life branches are locked, never deleted, and their docs stay online with an "end of life" banner.

### Installing an older line

Every line stays installable, and its docs stay online at `/docs/<branch>/` with the version switcher at the top of the menu:

```bash
npm create strutvane@0.2 my-app                # the newest 0.2 starter: a 0.2 app
npm install @strutvane/framework@latest-0.2    # the newest release of an older maintained line
npm create strutvane@next my-app               # a preview of the next line (not for production)
```

**What you'll see:** the starter prints the line it is creating, and the app's `package.json` uses `^0.2.x` ranges. The starter refuses an end-of-life line unless you pass `--allow-eol`.

## The core train and add-ons

The **core train** is the set of packages that always release together, with the same version number:

- `@strutvane/framework`
- `@strutvane/auth`
- `@strutvane/ui`
- the first-party designs, `@strutvane/design-crisp` and `@strutvane/design-vivid`
- `create-strutvane`, and the app skeleton it copies

So "Strutvane 0.2.4" means all of them at `0.2.4`, and one git tag `v0.2.4` marks the release.

**Add-ons** (`@strutvane/log-viewer`, `@strutvane/files`, `@strutvane/billing`, …) release on **their own** version numbers. Each declares the framework lines it works with as a **peer range**, a range npm checks against the framework your app already has:

```json title="node_modules/@strutvane/billing/package.json (excerpt)"
{
  "peerDependencies": {
    "@strutvane/framework": "^0.2.0"
  }
}
```

The [Package Catalogue](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/packages/catalogue/) records which add-on versions work with which framework line, and the installer only offers add-ons that match the framework it is installing. From 1.0, only an add-on's newest major gets fixes.

> **Two sources say different things here**
> ADR-0020 (proposed) puts **every** package in one train before 1.0 and lists the unscoped `strutvane` command in the train. Blueprint 18 §3.3 (decided on 2026-11-15, for 100+ packages) keeps the train to the core packages above and lets add-ons version on their own. This page follows the blueprint; the ADR is to be updated.

## How deprecations work

Before anything is removed, it is **deprecated** (marked as on its way out) for at least one full line:

- Your editor shows it struck through, with the replacement and the line that removes it (TSDoc `@deprecated`).
- At runtime, Strutvane logs one warning per process, with a stable code like `STRUTVANE_DEPRECATED_…` that tells you what to use instead.
- `STRUTVANE_DEPRECATIONS=throw` turns the warnings into errors (handy in tests); `off` silences them.
- `node strut doctor` lists the deprecated config keys and flags your app still uses.
- The [Deprecations page](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/deprecations/) lists everything deprecated in a line, and the release notes' "What's new" lists what was deprecated or retired in that line.

Removal happens only in a new breaking line: the next 0.x line before 1.0, the next major from 1.0. A renamed API keeps its old name as an alias for a full line. The only exception is a security fix, which may change behaviour at once; it's always announced, with an upgrade-guide entry.

A **package** that is no longer needed is retired the same way: its npm name gets `npm deprecate` with a pointer to the replacement, and its repository is archived (read-only, never deleted). That happens only **after** the replacement is released, so nobody is pointed at a version that doesn't exist yet.

```text
npm warn deprecated @strutvane/core@0.1.0-next.0: Merged into @strutvane/framework. Import from @strutvane/framework/core instead.
```

That is what `npm install` prints for a deprecated package (the wording of our message is not final).

## Security releases

**Please don't report security problems in public issues.** Use GitHub's private vulnerability reporting on the [Strutvane repository](https://github.com/vishwajit-vm/strutvane/security).

When a vulnerability is fixed:

- every affected line that still gets security fixes is released **on the same day**;
- a GitHub Security Advisory lists the fixed version for each line;
- `npm audit` reports it to you.

End-of-life lines get no fixes; the advisory tells you which line to move to. Every release is built in CI with npm provenance and approved by a maintainer with two-factor authentication before it goes live.

## Common mistakes

### `npm update` didn't move me to the next line

**Why:** `^0.2.4` means "any 0.2 release from 0.2.4 on", never 0.3. A new line may break things, so you move to it on purpose.

**Fix:** follow the [upgrade guide](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/upgrade/), then change the ranges of the core packages together:

```json title="package.json"
"@strutvane/framework": "^0.3.0"
```

### npm says an add-on's peer dependency doesn't match

```text
npm error ERESOLVE could not resolve
npm error While resolving: @strutvane/billing@0.4.1
npm error Found: @strutvane/framework@0.2.6
```

**Why:** that add-on version supports a different framework line than the one in your app.

**Fix:** install an add-on version made for your line (the catalogue lists them), or upgrade the core packages first:

```bash
npm install @strutvane/billing@^0.3
```

### The starter refuses an old line

```text
npm create strutvane@0.1 my-app
```

**Why:** 0.1 has reached end of life, so it gets no fixes, not even security fixes.

**Fix:** use the current line. To reproduce an old bug, pass `--allow-eol`:

```bash
npm create strutvane@0.1 my-app -- --allow-eol
```

> **Coming in 0.2**
> `--allow-eol`, the `latest-<line>` dist-tags and the support status in `node strut about` and `doctor` are designed (ADR-0020) and not built yet. The peer-range error above shows npm's usual output for such a mismatch; no Strutvane add-on is published yet.

### I'm reading the docs for the wrong line

**Why:** a search engine or an old link took you to another line's docs.

**Fix:** use the version switcher at the top of the menu; it keeps you on the same page when it exists. Links that start with `/docs/latest/` always go to the current line.

## Next steps

- [Release Notes](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/releases/): what's new, deprecated and retired in 0.2.
- [Upgrade Guide](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/upgrade/): moving an app from 0.1 to 0.2.
- [Package Catalogue](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/packages/catalogue/): every package and its status.
