# 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](installation.md), and
service commands are in [Deployment](deployment.md).

## Release identity and support

Releases are [GitHub releases](https://github.com/HarvardMadSys/hybridInference/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](https://github.com/HarvardMadSys/hybridInference/blob/dev/SECURITY.md).

### Include the version in a bug report

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

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

```bash
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](database.md#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](deployment.md#what-a-change-actually-requires) 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.