# Versioning and stability

> Understand Gyral's 0.x API policy, package versions, how to upgrade and which entry points are internal.

Source: https://gyral.dev/docs/versioning/

Gyral is in **0.x**. A minor version can include breaking changes. Read its upgrade guide
and the package changelogs before moving to it; do not treat every 0.x minor as an
interchangeable dependency update.

## Public and internal APIs

Use documented public package entries. Entries containing `/internal` are for Gyral's own
packages and have no stability promise. A symbol being technically exported does not make
an internal entry an application API. The
[export inventory](https://github.com/gyraljs/gyral/blob/v0.3.10/docs/references/public-api-0.3.1.md)
records the public boundary of 0.3.10: every entry and what it exports.

The `@gyral/*` packages and `create-gyral` release together at a shared version: keep every
`@gyral/*` package your app installs on that one version. Gyral's packages take `@gyral/core` as a
peer at their exact version, so your package manager reports a mismatch when it installs (pnpm
lists the unmet peer, npm stops with `ERESOLVE`), and a package that loads with another release
of core throws [G0016](https://gyral.dev/errors/#G0016) in development. The
[package guide](https://gyral.dev/docs/packages/#one-version-of-every-package) explains what each app needs.

## Releases

These guides describe **0.3.10**, the `latest` version on npm. Every package is published
from GitHub Actions with npm provenance; install from the registry. Today npm has releases
only, under the `latest` tag.

For a released application, pin the registry version you verified and retain the lockfile.
Deploy server output and client assets from the same build: stale HTML with new component
templates can cause hydration mismatches. Versioned hashed assets help keep that agreement.

Breaking changes wait for a new minor version, and that release gets an upgrade guide in these
docs. On an older 0.3.x release? Install 0.3.10 and read the
[core changelog](https://github.com/gyraljs/gyral/blob/main/packages/core/CHANGELOG.md).

## Upgrade with evidence

1. Read the changelogs for every release between yours and the target, and the upgrade guide
   when the target is a new minor version.
2. Update packages together and install from the lockfile.
3. Commit, then run `npx @gyral/codemod 0.3.8` from the app's directory, before or after you
   install. It moves code from 0.3.7's APIs to the current ones wherever it can prove the
   rewrite safe: a spread-in `gyralVitePreset()` becomes `plugins: [gyral()]`,
   `...(gyralVitePreset(o).plugins ?? [])` becomes `...gyral(o)`, driver records
   outside tests become [lists](https://gyral.dev/docs/effects/#substituting-drivers), and
   `subscription('feed', …)` becomes `subscription(feed, …)` where the module declares the
   `feed` token. An app on 0.3.8 has nothing to rewrite. A package whose `@gyral/core` is older
   than 0.3.7 is left as it is, and reported once if it has code to rewrite: migrate it to 0.3.7
   first. The codemod lists every candidate it leaves, with `file:line` and the reason, among
   them driver records it can't follow (returned from a function, passed in
   `defineStore({ drivers })` options) and `subscription('feed', …)` where `feed` is imported
   from another module. It only writes into a clean git working tree (`--dry` prints the diff
   instead), so `git diff` shows what it did.
4. Run ESLint with `gyral.configs.recommended` from `@gyral/core/eslint`. `gyral/prefer-built-in`
   names code that a built-in replaces, such as a parser that checks modifier keys by hand
   (`on()`) or `JSON.parse` of a prop, whatever the props parameter is called (`prop.json()`),
   and `gyral/intent-event` an `on()` parser bound to another event
   ([the rules](https://gyral.dev/docs/packages/#the-eslint-plugin)).
5. Run typechecking, component/browser tests and the production build. `vite dev` and browser
   tests run Gyral's development checks, and some throw, naming what to change. A view that
   reads something besides its state, props and stores warns ([G0017](https://gyral.dev/errors/#G0017)),
   because Gyral skips renders whose inputs are unchanged.
6. Test server/client hydration, edited forms, routing and the production CSP if your app
   uses them. Check payload size for the pages whose loading matters. If `gyral-rs` renders
   your pages, check that your `gyral-rs` release accepts the target
   ([Rust servers](https://gyral.dev/docs/rust-servers/#embedded-rendering-with-gyral-rs)).
7. Update the agent skill your project carries:
   `npx @gyral/mcp@0.3.10 skill` ([coding agents](https://gyral.dev/docs/coding-agents/#the-agent-skill)).

The generated [API reference](https://gyral.dev/docs/api/) describes the packages installed for this site's
build. Consult the changelog for the exact version your app runs:
[core](https://github.com/gyraljs/gyral/blob/main/packages/core/CHANGELOG.md),
[HTTP](https://github.com/gyraljs/gyral/blob/main/packages/http/CHANGELOG.md),
[router](https://github.com/gyraljs/gyral/blob/main/packages/router/CHANGELOG.md),
[SSR](https://github.com/gyraljs/gyral/blob/main/packages/ssr/CHANGELOG.md) and the other package
directories. Report a regression with the versions, a small reproducer and the expected
behavior. The repository's `pnpm check` is its release-quality gate.