# 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.6/docs/references/public-api-0.3.1.md)
records the public boundary of 0.3.6: every entry and what it exports.

The `@gyral/*` packages and `create-gyral` release together at a shared version. Keep core, router,
HTTP, time, testing, devtools, SSR and MCP aligned; verify your lockfile when a package manager
resolves multiple versions. The [package guide](https://gyral.dev/docs/packages/) explains what each app needs.

## Releases

These guides describe **0.3.6**, 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.6 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. Run typechecking, component/browser tests and the production build.
4. 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.

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.