Versioning and Support

This page is for the people who deploy and maintain an instance of Open Data Capture. It says what a version number promises, which versions receive fixes, and how to install and upgrade so that your instance runs a release rather than unreleased code.

What a version number promises

A version is <major>.<minor>.<patch>, for example 2.6.0. Within one major, upgrading to a newer release is always safe: it keeps every promise below. A release that breaks any of them is a new major, and its changelog lists each break under Breaking Changes, with what you have to do.

Stored data. An upgrade starts against your existing database and file storage and reads every existing record, with no manual step.
Deployment configuration. This covers the variables in .env and the services, volumes and ports in the Docker Compose stack. A new variable has a default that keeps the old behaviour. Renaming or removing a variable, or making it required, is a breaking change. So the newest images of a major work with the compose file from any earlier release of that major.
Stored instruments. Every instrument already in your database keeps rendering, and its records keep exporting.
The documented HTTP API, as the API’s OpenAPI document (spec.json) describes it. Additions are allowed; removing or changing anything is a breaking change.
Export formats. Column and field names stay the same.
Access. An upgrade never widens or narrows what an existing user can see or do, unless an administrator acts. The one exception is the fix for a security issue that gave users access they were never meant to have: that fix is not a breaking change, and its advisory says so.
The public API and command-line interface of each package published to npm.

The promise does not cover the layout and workflows of the user interface, undocumented API endpoints, internal packages, or the protocol between the gateway and the API. The gateway and the API must always run the same version.

You can upgrade directly from any release of a major to the newest release of the same major. You do not need to install the releases in between.

Which versions are supported

The current major is supported in its newest release only. To receive a fix, upgrade to the newest release of the current major, which the promise above makes safe.
A superseded major keeps its last minor version supported for 18 months after the next major is released.
Versions before 2.0.0 are not covered by this policy.

Major	Released	Superseded	Supported until
2	2026-06	—	—

A major with no superseded date is the current one, and it stays supported until 18 months after its successor is released. Each date is a month: a major superseded in 2026-11 is supported until the end of 2028-05.

What each version receives

Fix	Current major (newest release)	Newest superseded major	Older superseded majors
Security	✓	✓	✓
Data integrity	✓	✓	✓
Critical bug	✓	✓	—
Everything else	✓	—	—

Security means either of two things:
- A vulnerability that lets someone, in a documented deployment configuration (the Docker Compose stack and its documented options, including optional ones), do any of the following:
  1. read data they are not authorized to see;
  2. create, change or delete data they are not authorized to;
  3. act as another user, or gain permissions they were not given;
  4. run code on the server or in another user’s browser.
- Or a vulnerability rated Critical in anything a deployment runs: the base image, its operating system packages, the npm dependencies the API, gateway and web app run with, and the third-party images the Docker Compose stack uses (MongoDB, RustFS and Caddy).
A severity score on its own does not make an issue a security issue.
Data integrity means a bug that silently loses, corrupts or misattributes recorded data, or exports it incorrectly.
Critical bug means the stack fails to start, or a core workflow is unusable with no workaround. The core workflows are administering an instrument, collecting a remote assignment, managing subjects and users, and exporting data. An availability problem, such as a crash or resource exhaustion, counts as a critical bug when a user can trigger it and it makes a core workflow unusable. Any other availability problem is fixed in the next ordinary release of the current major.

The maintainers judge whether an issue can be reached and whether a workaround exists. If a fix cannot be applied to a supported version without breaking it, for example because the fix exists only in the next major of a dependency, we publish an advisory saying which versions are affected and recommending an upgrade.

Choosing an image tag

RELEASE_CHANNEL in .env chooses the tag of the Open Data Capture images that Docker Compose pulls.

Tag	Moves when	Use it for
`<major>`	every release of that major, including fixes	the default: production deployments that want every fix and never a breaking change
`<version>`	never	production deployments that upgrade by hand, one release at a time
`latest`	every release of the newest major	demonstrations and quick starts only: it crosses majors, so it can bring a breaking change
`edge`	every change to the `main` branch	development and testing; it is unreleased code
`sha-<7>`	never	pinning one exact build of the `main` branch

A generated .env tracks the current major, for example RELEASE_CHANNEL=2. Moving to the next major is always a choice you make: read the Breaking Changes of its first release in the changelog, then set RELEASE_CHANNEL to the new major.

Installing and upgrading

Install from a release tag, never from the main branch, so that the compose file you run belongs to a release. Replace <version> with the newest version on the releases page:

git clone --branch v<version> https://github.com/DouglasNeuroInformatics/OpenDataCapture.git

To upgrade, check out the newer release and restart the stack:

git fetch --tags
git checkout v<newer-version>
docker compose pull
docker compose up -d

.env and the mongo, rustfs and sqlite directories are ignored by git, so switching between releases never touches your configuration or your data.

Hearing about new releases

Releases: on the repository page, choose Watch → Custom → Releases.
Security advisories: choose Watch → Custom → Security alerts as well. Every security fix gets a GitHub Security Advisory that lists the affected and the fixed versions of each supported major.
Data integrity fixes are not vulnerabilities, so they get no advisory. The release notes say which versions were affected.

To report a vulnerability, follow the security policy.

npm packages

The packages published to npm carry the same version numbers as the platform, but they are published only from the newest major. A fix to a superseded major ships as images and a GitHub release, not to npm. To stay on one major in your own project, depend on ^<major>, for example ^2.