docs/overview/versioning-policy.md
The Backstage project is comprised of a set of software components that together form the Backstage platform. These components are both plugins as well as core platform libraries and tools. Each component is distributed as a collection of packages, which in the end is what you end up consuming as an adopter of Backstage.
The number of Backstage packages that build up an application can be quite large, in the order of hundreds, with just the core platform packages being counted in the dozen. This creates a challenge for the integrators of a Backstage project, as there are a lot of moving parts and pieces to keep up to date.
Our solution to this is collecting our most used components and their packages into an umbrella version that we call a Backstage release. Each release is a collection of packages at specific versions that have been verified to work together. Think of it as a toolbox that comes with batteries included, but you can always add more plugins and libraries from the open source ecosystem as well as build your own.
The Backstage project is structured around two different release lines, a primary "main" release line, and a "next" release line that serves as a preview and pre-release of the next main-line release. Each of these release lines have their own release cadence and versioning policy.
Release cadence: Monthly, specifically on the Tuesday before the third Wednesday of each month. The first release took place in March 2022.
The main release line is versioned with a major, minor and patch version but
does not adhere to semver. The version format is
<major>.<minor>.<patch>, for example 1.3.0.
An increment of the major version denotes a significant improvement or change to the Backstage platform. It may come with a large new set of features, or a switch in the product direction. These will be few and far between, and do not have any set cadence. Policy-wise they are no different than a minor release.
Each regularly scheduled release will bring an increment to the minor version, as long as it is not a major release. Each new minor version can contain new functionality, breaking changes, and bug fixes, according the versioning policy.
Patch versions will only be released to address critical bug fixes. They are not bound to the regular cadence and are instead released whenever needed.
Release cadence: Weekly, specifically on Tuesdays.
The next release line is a weekly release of the project. Consuming these releases gives you early access to upcoming functionality in Backstage. There are however fewer guarantees around breaking changes in these releases, where moving from one release to the next may introduce significant breaking changes.
The following versioning policy applies to the main-line releases only.
>=1.0.0 will only be
done when necessary and with the goal of having minimal impact. When possible,
there will always be a deprecation path for a breaking change.high or critical will always be backported to releases
for the last 6 months if feasible.In order for Backstage to function properly the following versioning rules must be followed. The rules are referring to the Package Architecture.
It is allowed and often expected that the "Plugin Core" and "Library" packages are from older releases than the "App Core" packages. It is also allowed to have duplicate installations of the "Plugin Core" and "Library" packages. This is all to make sure that upgrading Backstage is as smooth as possible and allows for more flexibility across the entire plugin ecosystem.
Every individual package is versioned according to semver.
This versioning is completely decoupled from the Backstage release versioning,
meaning you might for example have @backstage/core-plugin-api version 3.1.4
be part of the 1.12 Backstage release.
The following versioning policy applies to all packages:
**BREAKING**: in the changelog.For packages at version 1.0.0 or above, the following policy also applies:
@alpha or @beta exports must result in at least a minor
version bump, and may be done without a deprecation period.There are a few changes that would typically be considered breaking changes, but that we make exceptions for. This is both to be able to evolve the project more rapidly, also because the alternative ends up having a bigger impact on users.
For all Utility APIs and Backend Services that have a built-in implementation, we only consider the API stability for consumers of those interfaces. This means that it is not considered a breaking change to break the contract for producers of the interface.
Changes that fall under the above rule, must be marked with
**BREAKING PRODUCERS**: in the changelog.
For any case of dependency injection, it is not considered a breaking change to
add a dependency on a Utility API or Backend Service that is provided by the
framework. This includes any dependency that is provided by the
@backstage/app-defaults and @backstage/backend-defaults packages.
The release stages(@alpha, @beta @public) refers to the
TSDoc documentation tag of the export, and are also
visible in the API report of each package.
Backstage uses three stages to indicate the stability for each individual package export.
@public - considered stable and are available in the main package entry
point.@beta - Not visible in the main package entry point, beta exports must be
accessed via <package-name>/beta or <package-name>/alpha imports.@alpha - here be dragons. Not visible in the main package entry point, alpha
exports must be accessed via <package-name>/alpha imports.The Backstage project uses Node.js for both its development tooling and backend runtime. In order for expectations to be clear we use the following schedule for determining the Node.js releases that we support:
engines field in the root package.json of a new app.When we say Supporting a Node.js release, that means the following:
@backstage/create-app will have their engines.node version set accordingly.Based on the above Backstage supports Node.js 22 and 24 as of the 1.46.0 release.
The Backstage project uses TypeScript for type checking within the project, as well as external APIs and documentation. It is important to have a clear policy for which TypeScript versions we support, since we want to be able to adopt new TypeScript features, but at the same time not break existing projects that are using older versions.
The TypeScript release cadence is roughly every three months. An important aspect of the TypeScript versioning is that it does not follow semver. In particular, there is no differentiation between major and minor versions, both of them are breaking. One way to think about it is to merge the two, for example version 4.7 can be considered major version 47, 5.0 is 50, and so on. Within these releases there can be a number of patch releases, which do follow semver.
Our policy is to support the last 3 TypeScript versions, for example 4.8, 4.9, and 5.0. Converted to time, this means that we typically support the TypeScript version from the last six to nine months, depending on where in the TypeScript release window we are. This policy applies as a snapshot at the time of any given Backstage release, new TypeScript releases only apply to the following Backstage main-line release, not to the current one.
For anyone maintaining their own Backstage project, this means that you should strive to bump to the latest TypeScript version at least every 6 months, or you may encounter breakages as you upgrade Backstage packages. If you encounter any issues in doing so, please file an issue in the main Backstage repository, as per this policy we should always support the latest version. In order to ensure that we do not start using new TypeScript features too early, the Backstage project itself uses the version at the beginning of the currently supported window, in the above example that would be version 4.8.
The Backstage project recommends and supports using PostgreSQL for persistent storage.
The PostgreSQL versioning policy is to release a new major version every year with new features which is then supported for 5 years after its initial release.
Our policy mirrors the PostgreSQL versioning policy - we will support the last 5 major versions. We will also test the newest and oldest versions in that range. For example, if the range we support is currently 14 to 18, then we would only test 14 and 18 explicitly.