Releases and upgrades

Use a published release as the starting point for an installation you operate. Contributions target dev. This page explains how to identify what is running and plan an upgrade; initial setup is in Installation, and service commands are in Deployment.

Release identity and support

Releases are GitHub releases tagged with the UTC date, YYYYMMDD; another release on the same date gets .1, .2, and so on. They are dated snapshots, not semantic-version compatibility promises. A maintainer cuts one by moving main up to a commit on dev; the Release workflow then publishes the release with generated change notes.

Identifier

What it tells you

A published date tag

A fixed source snapshot with GitHub release notes

main

The branch maintainers move up to dev for each release; it moves over time

dev or a feature branch

Development work that may be newer than the latest release

A full commit SHA

The exact source revision; include local modifications separately

An image digest, image@sha256:…

The exact container artifact, which may differ from the host checkout

CI publishes backend and console candidates with dev-<full-sha> tags and short-SHA aliases. A candidate tag identifies development output; it does not mean a date release exists for that commit. The 0.1.0 values in pyproject.toml and apps/frontend/package.json are package metadata and do not identify a particular deployed build.

Report problems against the latest published release when possible. Fixes normally land on dev and reach a later release. There is no documented LTS branch, guaranteed backport window or response-time commitment; do not assume an older release receives fixes automatically. An older-version report is still useful: include its exact revision and whether the problem also occurs on the latest release. Security reports follow the security policy.

Include the version in a bug report

For source installs, run these in the checkout used to build or start the service:

git rev-parse HEAD
git describe --tags --exact-match HEAD
git status --short

The second command reports an error when HEAD is not exactly tagged; report the SHA in that case. Mention local changes without pasting secrets or private configuration.

For the standard Compose stack, inspect the running artifacts:

docker inspect --format '{{.Name}} image={{.Config.Image}} id={{.Image}}' \
  hybridinference-backend hybridinference-frontend

Use your deployment’s container names if they differ. Include any pinned image digests from its deployment configuration. The console footer also shows the build SHA when supplied at build time; build dev / local build means that metadata was omitted. The footer identifies the console build, so report the backend revision separately when the two were deployed independently.

Compatibility and breaking changes

Read the notes and linked PRs for every release between your installed version and the target. A date tag alone does not establish compatibility, and the OpenAI-compatible API does not imply support for every provider extension. Check the endpoints, streaming behavior and model settings your clients use.

Contributors changing an HTTP contract, authentication, an environment or YAML setting, a default, or database schema should state the old and new behavior in the PR. Identify who must act, give the configuration or migration steps, and explain whether the previous version can still use the resulting data. Mark breaking changes explicitly in the PR and release notes; autogenerated commit summaries alone do not explain how an operator should upgrade.

Upgrade and rollback

  1. Record the current and target release/commit, backend and console image identities, and the active distribution/configuration. Keep the previous artifacts available so rollback does not depend on rebuilding them.

  2. Read the target’s configuration requirements. Preserve the deployment’s existing .env, overlay and secrets; merge required changes instead of replacing them with fresh example files. Keep JWT_SECRET_KEY, API_KEY_SECRET and ERASURE_FENCE_SECRET stable across replicas and upgrades. Changing the first invalidates access tokens, changing the second makes existing API-key hashes unverifiable, and changing the third — or the second, while it stands in for the third — stops the backend from starting. An upgrade is not a secret-rotation procedure.

  3. Back up each configured database and check that the backup restores into a separate database. Protect a matching copy of the configuration and secrets. See Database backup for the standard Postgres commands; use the storage provider’s backup procedure for other deployments.

  4. Rehearse on an isolated local or staging deployment, using separate storage and suitable test data. The application creates and updates schema on startup, so merely starting a new backend against a database can change it. Check startup logs and /health/ready, then login, an existing API key, a routed request and streaming if your clients use it.

  5. Deploy the selected revision using your existing deployment method. For the standard stack built from source, make build rebuilds and recreates services from the current checkout; make restart keeps existing images. See Deployment for the distinction between rebuilding code and reloading configuration. Check the running artifact identities and repeat the rehearsal checks before sending normal traffic to it.

Returning to a previous image does not undo database changes. If the previous version is compatible with the upgraded schema and data, restore its matching application artifacts and configuration. Otherwise, stop application writers and restore the matching pre-upgrade database backup before restarting the previous version. This discards writes made since the backup, so account for those writes in the recovery plan. There is no general automatic schema downgrade command; make down preserves data and deleting a volume is a reset, not a rollback.