Releases and maturity levels

Overview

This page explains the release process of Prisma, how it's versioned and how to deal with breaking changes that might happen throughout releases.

Releases

Prisma releases typically happen every two weeks. Note that this is not a hard rule, releases might be postponed for internal reasons.

Product maturity levels

A release can inclue products or features at different maturity levels. Maturity level describes a product or feature's completeness, and what users can expect in terms of breaking changes.

Experiment

If a feature or product is an Experiment:

  • We want to test whether a problem genuinely exists and if a proposed prototype would solve it.
  • We are not yet clear about whether we want to add it to the product surface.

Not recommended for production.

Early Access

If a feature or product is Early Access:

  • We have validated a problem and are considering a solution to it, but are not certain whether that solution is complete or a perfect fit.
  • We want to gather more feedback and adjust the solution as necessary, knowing that users are prepared for significant breaking changes

Not recommended for production.

Preview

If a feature or product is a Preview:

  • We have validated the feature or product in terms of direction and surface.
  • Users can count on the feature or product and associated API to be mostly stable, unless stated otherwise in the release notes and documentation.
  • There are no significant known issues, although smaller bugs may exist.
  • We welcome feedback on these to make the solution stable as quickly as possible.

Previews are typically available behind a feature flag or require some form of opt-in (for example, by providing a --preview-feature flag in the CLI).

Not recommended for production.

Generally Available (GA)

If a feature or product is Generally Available:

  • The solution has been tested for some time and we received enough feedback to consider it stable and ready for production use.
  • There should be no bugs in 99% of cases (completely bug-free software cannot be guaranteed)

Versioning

Prisma's approach for versioning is inspired by Semantic Versioning (SemVer) but doesn't fully adhere to it.

Prisma vs SemVer

How does SemVer versioning work?

Semantic Versioning (SemVer) uses the following rules for version upgrade (quoted from the SemVer spec):

Given a version number MAJOR.MINOR.PATCH, increment the:

  1. MAJOR version when you make incompatible API changes,
  2. MINOR version when you add functionality in a backwards compatible manner, and
  3. PATCH version when you make backwards compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

How does Prisma versioning work?

While Prisma releases follow the format of the Semantic Versioning (SemVer) specification, it does not follow the rule that MINOR version updates must not have incompatible API changes (i.e. breaking changes). This means that there might be breaking changes in any 2.X release.

Given a version number MAJOR.MINOR.PATCH, Prisma's version number is incremented as follows:

  1. MAJOR version is incremented when major product updates (likely with breaking changes) are released,
  2. MINOR version is incremented for minor product updates (may have breaking API changes) are released, and
  3. PATCH version functionality is added or bugs are fixed (backwards compatible).

Why does Prisma not follow SemVer?

Prisma is one of many developer tools that doesn't follow the SemVer specification. The main reason is that Prisma has a huge developer surface made up by several tools (the Prisma CLI, Prisma Client, Prisma Migrate, Prisma Studio, ...). Therefore, a breaking change in one tool might not affect usage of another tool, so incrementing the major version number for the tools that are not affected might not be justified.

Edit this page on GitHub