Prisma Adopts Semantic Versioning (SemVer)

TL;DR

Here is a brief overview of the new rules we are putting in place:

• By adopting SemVer, we're making it easier for users to understand which version may contain breaking changes. The adoption of SemVer is merely a change to our release policy to be consistent with industry practices and improve the developer experience.
• Breaking changes in stable surface (i.e. General Availability) will only be introduced in new major versions.
• Breaking changes can still be rolled out in minor versions but only for opt-in Preview and Early Access features that are not active by default (e.g. via a Preview feature flag or a specific opt-in option or new CLI command).
• Opt-in breaking changes, i.e. Preview and Early Access, released in minor versions will only be promoted to General Availability (no requirement for opt-in) in new major versions.

You can read more details about this in the Releases and maturity levels section in our documentation.

Prisma releases adopt SemVer

Semantic Versioning (SemVer) is a conventional release strategy that has clear rules for when users can expect breaking changes in a software release.

While we already followed the 3-digit SemVer notation for Prisma releases, we didn't quite follow the actual SemVer semantics yet. This meant that we sometimes released breaking changes upon minor version increments.

In the future, breaking changes in minor version increments will always be opt-in. Any breaking change to the stable developer surface of the Prisma ORM will only happen in major version increments.

Currently, it's hard for users to understand which version may or not contain breaking changes. When upgrading through multiple versions, e.g. from 2.13.0 to 2.26.0, you have to read the release notes of each intermediate release to determine which breaking changes will impact you – this makes it hard to navigate breaking changes.

What this means for you?

In essence, the new release policy doesn't change anything about how you use Prisma and the ongoing evolution of Prisma. We're just making it easier for you to understand which version may contain breaking changes.

Prisma will continue to document the exact details for upcoming breaking changes in the release notes. Additionally, we will provide upgrade guides to help with the upgrade path between major releases.

Many of the package managers and dependency automation tools in the industry were designed with SemVer in mind, e.g. Renovate and Dependabot. They save you time by automating parts of the dependency upgrade process, creating pull requests with relevant release changes, and automatically merging non-breaking changes.

Why we are adopting SemVer semantics

Updating dependencies can be a time-consuming process – especially in projects with many dependencies. Adhering to Semver should improve your upgrade experience as breaking changes become predictable and visible moving forward.

SemVer is a widely used industry standard, especially in the Node.js ecosystem.

As we're seeing more developers and companies adopt Prisma and getting helpful feedback about our release strategy, we've decided to adjust our release strategy and fully adopt SemVer in the future.

One of Prisma's upcoming releases will have breaking changes

One of the upcoming Prisma releases will come with breaking changes. Following our new release strategy, the major version number will be incremented, and Prisma's new version will therefore be 3.x.x.

You can read more about our release strategy in the documentation.