From 2853bf004f6061a259fa9a0a22f88fc2172cce6c Mon Sep 17 00:00:00 2001 From: Daniel Szoke Date: Thu, 11 Dec 2025 13:29:35 +0100 Subject: [PATCH] meta(versioning): Define versioning policy (#3025) ### Description Explicitly define a versioning policy that we will follow in Sentry CLI 3.0 and onwards. This policy intentionally defines our public API narrowly. The goal is to preserve flexibility in how we maintain the CLI, while providing users clarity on which features they can consider stable. ### Issues - Resolves #2594 - Resolves [CLI-132](https://linear.app/getsentry/issue/CLI-132/add-version-supportsemver-policies) --- CHANGELOG.md | 7 +++++++ README.md | 4 ++++ VERSIONING.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 59 insertions(+) create mode 100644 VERSIONING.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 02564d8b9b..9b14f04a30 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,13 @@ `sentry-cli` 3.0.0 and above only officially supports Sentry SaaS and Sentry self-hosted versions [25.11.1](https://github.com/getsentry/sentry/releases/tag/25.11.1) and higher. While many Sentry CLI features may, in practice, continue working with some older Sentry versions, continued support for Sentry versions older than 25.11.1 is not guaranteed. Changes which break support for Sentry versions below 25.11.1 may occur in minor or patch releases. +### New Versioning Policy + +Sentry CLI now defines a [semantic versioning policy](VERSIONING.md). We did not explicitly define a versioning policy before, but the new versioning policy contains some notable changes versus the previous implicit policy we had been following. The main change is that dropping support for self-hosted Sentry versions now only requires a minor version bump, although such changes will be clearly communicated in the changelog. + +> [!IMPORTANT] +> **Self-hosted users**: We strongly recommend pinning your Sentry CLI version, since Sentry CLI may drop support for your self-hosted Sentry version in any future minor release. Always check the changelog before upgrading Sentry CLI. + ### Breaking Changes - Removed all `sentry-cli files ...` and `sentry-cli releases files ...` subcommands ([#2956](https://github.com/getsentry/sentry-cli/pull/2956)). These commands provided functionality for managing release files, a feature that has been deprecated in Sentry. Users still using `sentry-cli files upload` to upload source maps should migrate to `sentry-cli sourcemaps upload`. diff --git a/README.md b/README.md index 284608425a..c1f4a2a3ef 100644 --- a/README.md +++ b/README.md @@ -35,6 +35,10 @@ For users who cannot upgrade their self-hosted installation, we recommend using Note that we can only provide support for officially-supported Sentry Self-Hosted versions. We will not backport fixes for older Sentry CLI versions, even if they should be compatible with your self-hosted version. +## Versioning + +Sentry CLI follows semantic versioning, according to [this versioning policy](VERSIONING.md). + ## Compiling In case you want to compile this yourself, you need to install at minimum the diff --git a/VERSIONING.md b/VERSIONING.md new file mode 100644 index 0000000000..a715006bbf --- /dev/null +++ b/VERSIONING.md @@ -0,0 +1,48 @@ +# Versioning Policy + +Sentry CLI follows [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html). This policy defines Sentry CLI's public API and provides examples of how we would apply this policy. + +## Public API + +For the purposes of Semantic Versioning, Sentry CLI's public API is defined as the following: + - All subcommands and command line arguments. + - All publicly exposed functions/methods of the JavaScript API (only available via the [NPM package](https://www.npmjs.com/package/@sentry/cli)). + - This versioning policy document. + +Any of the above items, which are explicitly marked as "experimental," "beta," or similar, are not part of the public API, and are subject to change at any time. + +**Anything, which is not explicitly defined as part of the public API, is not part of the public API.** In particular, for semantic versioning purposes, the following items are not part of the public API: + - Compile-time feature flags, dependencies, MSRV, etc., as we expect most users to use the prebuilt binaries we supply. + - Any changes to output wording/formatting/etc. + - The minimum self-hosted Sentry version that we support. + - Any public items exported from the `sentry-cli` Rust crate, as we do not publish `sentry-cli` to crates.io, and thus do not expect anyone to use it as a library. + +> [!NOTE] +> Although this document intentionally defines the public API narrowly, we aim to avoid unnecessary breakage of features users rely on. We will call out notable behavioral changes in the changelog regardless of version bump. + +## Examples + +This section lists examples of changes which would require a major, minor, or patch version bump. All of the lists are non-exhaustive. + +### Major Version + +The following changes would require a major version bump, unless the affected item is specifically marked as "experimental," "beta," or similar: + - Removal of a subcommand or an argument to a subcommand. + - A reduction in the accepted values that can be passed to a command line argument, unless this reduction is necessary to fix a bug, for example, because the argument never handled certain values correctly. + - Removal of a publicly exposed function/method of the JavaScript API, or any other backwards-incompatible change to these. + - Any change to this versioning policy, which narrows the public API definition. + +### Minor Version + +The following changes would only require a minor version bump: + - A new subcommand or command line argument is added, unless this new item is "experimental," "beta," or similar. + - A new public item is added to the JavaScript API, unless this new item is "experimental," "beta," or similar. + - An item which was previously marked "experimental," "beta," or similar has this designation removed, thus being added to the public API. + - The minimum self-hosted Sentry version supported by Sentry CLI is increased. Such changes will always be clearly mentioned in the changelog. + +### Patch Version + +The following changes may occur in a patch version: + - Bug fixes, which do not alter public API. + - Changes to compile-time feature flags, dependencies, MSRV, etc., though we may often opt to do such changes in a minor. + - Changes which break functionality which previously had worked with a version of self-hosted Sentry, which we do not officially support.