From 4373a3b662a429e223ae5bb2d2cddb354ff49293 Mon Sep 17 00:00:00 2001 From: jeanregisser Date: Tue, 7 Apr 2026 20:59:43 +0000 Subject: [PATCH 1/6] Add Versioning section to README Document the SDK's versioning policy, specifically: - All modules share a single version number - Breaking changes to @_spi (beta/preview) APIs require a MINOR bump - This is because podspecs use ~> X.Y.Z, so a breaking SPI change in a PATCH release could break consumers like stripe-react-native - @_spi APIs carry no long-term stability guarantees Committed-By-Agent: goose --- README.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/README.md b/README.md index 61a5fead59fb..0067c038ff70 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,7 @@ Table of contents * [Features](#Features) * [Releases](#Releases) + * [Versioning](#Versioning) * [Requirements](#Requirements) * [Getting started](#Getting-started) * [Integration](#Integration) @@ -110,6 +111,23 @@ For other modules, follow the instructions below: If you're reading this on GitHub.com, please make sure you are looking at the [tagged version](https://github.com/stripe/stripe-ios/tags) that corresponds to the release you have installed. Otherwise, the instructions and example code may be mismatched with your copy. +## Versioning + +All modules in the Stripe iOS SDK share a single version number and roughly follow [Semantic Versioning](https://semver.org/). + +There is one notable difference: **changes to `@_spi` APIs (used for beta/preview features) require at least a MINOR version bump**, even if those changes are breaking. This is because our CocoaPods podspecs pin inter-module dependencies using `~> X.Y.Z` (allowing only patch-level increases). Shipping a breaking `@_spi` change in a PATCH release could unexpectedly break consumers—such as `stripe-react-native`—that depend on those APIs. + +In summary: + +| Change type | Minimum version bump | +|---|---| +| Breaking change to public API | **MAJOR** | +| Breaking change to `@_spi` (beta/preview) API | **MINOR** | +| New public API or functionality | **MINOR** | +| Bug fixes, non-breaking changes | **PATCH** | + +> **Note:** `@_spi` APIs are pre-release and carry no long-term stability guarantees. Consumers of these APIs should expect breaking changes across minor versions. + ## Requirements The Stripe iOS SDK supports all [Apple supported Xcode versions](https://developer.apple.com/news/upcoming-requirements/) and is compatible with apps targeting iOS 13 or above. We support Catalyst on macOS 11 or later. From d824431518ce925c3d9d9fb57feb47aa1cfe62ea Mon Sep 17 00:00:00 2001 From: Jean Regisser Date: Tue, 7 Apr 2026 15:19:36 -0600 Subject: [PATCH 2/6] Link to README versioning docs from public API check PR comment Committed-By-Agent: claude --- .github/workflows/verify-public-interface.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/verify-public-interface.yml b/.github/workflows/verify-public-interface.yml index bf277bbc57a5..defc71d2ddc3 100644 --- a/.github/workflows/verify-public-interface.yml +++ b/.github/workflows/verify-public-interface.yml @@ -71,7 +71,7 @@ jobs: If you confirm these APIs need to be added/updated and have undergone necessary review, add the label `modifies public API` to this PR to acknowledge the interface change. Additionally, if you modified or removed an existing API, ensure you update the changelog to reflect the necessary version bump for your changes. Regular public API changes require a MAJOR version bump, and SPI API changes (other than `@_spi(STP)`-only declarations) require a MINOR or MAJOR version bump. - ℹ️ If this comment appears to be left in error, make sure your branch is up-to-date with `master`. + ℹ️ See the [Versioning](https://github.com/stripe/stripe-ios#versioning) section of the README for more details. If this comment appears to be left in error, make sure your branch is up-to-date with `master`. edit-mode: replace comment-id: ${{ steps.find_comment.outputs.comment-id }} issue-number: ${{ github.event.pull_request.number }} From 0909f53219e208bdcb6ac1eff6cbfe5699863d13 Mon Sep 17 00:00:00 2001 From: Jean Regisser Date: Wed, 8 Apr 2026 16:50:11 -0600 Subject: [PATCH 3/6] Simplify preview API note and remove stale versioning link from workflow Committed-By-Agent: claude --- .github/workflows/verify-public-interface.yml | 2 +- README.md | 18 +----------------- 2 files changed, 2 insertions(+), 18 deletions(-) diff --git a/.github/workflows/verify-public-interface.yml b/.github/workflows/verify-public-interface.yml index defc71d2ddc3..bf277bbc57a5 100644 --- a/.github/workflows/verify-public-interface.yml +++ b/.github/workflows/verify-public-interface.yml @@ -71,7 +71,7 @@ jobs: If you confirm these APIs need to be added/updated and have undergone necessary review, add the label `modifies public API` to this PR to acknowledge the interface change. Additionally, if you modified or removed an existing API, ensure you update the changelog to reflect the necessary version bump for your changes. Regular public API changes require a MAJOR version bump, and SPI API changes (other than `@_spi(STP)`-only declarations) require a MINOR or MAJOR version bump. - ℹ️ See the [Versioning](https://github.com/stripe/stripe-ios#versioning) section of the README for more details. If this comment appears to be left in error, make sure your branch is up-to-date with `master`. + ℹ️ If this comment appears to be left in error, make sure your branch is up-to-date with `master`. edit-mode: replace comment-id: ${{ steps.find_comment.outputs.comment-id }} issue-number: ${{ github.event.pull_request.number }} diff --git a/README.md b/README.md index 0067c038ff70..e0620db0513b 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,6 @@ Table of contents * [Features](#Features) * [Releases](#Releases) - * [Versioning](#Versioning) * [Requirements](#Requirements) * [Getting started](#Getting-started) * [Integration](#Integration) @@ -111,22 +110,7 @@ For other modules, follow the instructions below: If you're reading this on GitHub.com, please make sure you are looking at the [tagged version](https://github.com/stripe/stripe-ios/tags) that corresponds to the release you have installed. Otherwise, the instructions and example code may be mismatched with your copy. -## Versioning - -All modules in the Stripe iOS SDK share a single version number and roughly follow [Semantic Versioning](https://semver.org/). - -There is one notable difference: **changes to `@_spi` APIs (used for beta/preview features) require at least a MINOR version bump**, even if those changes are breaking. This is because our CocoaPods podspecs pin inter-module dependencies using `~> X.Y.Z` (allowing only patch-level increases). Shipping a breaking `@_spi` change in a PATCH release could unexpectedly break consumers—such as `stripe-react-native`—that depend on those APIs. - -In summary: - -| Change type | Minimum version bump | -|---|---| -| Breaking change to public API | **MAJOR** | -| Breaking change to `@_spi` (beta/preview) API | **MINOR** | -| New public API or functionality | **MINOR** | -| Bug fixes, non-breaking changes | **PATCH** | - -> **Note:** `@_spi` APIs are pre-release and carry no long-term stability guarantees. Consumers of these APIs should expect breaking changes across minor versions. +> **Note on preview APIs:** Some modules expose preview/beta APIs via `@_spi` annotations. These carry no stability guarantees and may have breaking changes in minor versions. ## Requirements From c7972011ecdba1ab7096e112eecb37f8142f7ced Mon Sep 17 00:00:00 2001 From: davidme-stripe <52758633+davidme-stripe@users.noreply.github.com> Date: Wed, 8 Apr 2026 16:17:29 -0700 Subject: [PATCH 4/6] Add preview APIs section to README Added a section on preview APIs and their stability guarantees. --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e0620db0513b..6fdb6783024e 100644 --- a/README.md +++ b/README.md @@ -64,6 +64,10 @@ The Stripe iOS SDK collects data to help us improve our products and prevent fra For help with Apple's App Privacy Details form in App Store Connect, visit [Stripe iOS SDK Privacy Details](https://support.stripe.com/questions/stripe-ios-sdk-privacy-details). +#### Preview APIs + +Some modules expose preview APIs via `@_spi` annotations. We aim to make breaking changes to these APIs only in major or minor releases, while retaining API compatibility across patch versions. (For example, a preview API may change when moving from version `12.1.0` to `12.2.0`, but should not change from `12.2.0` to `12.2.1`.) Please see the [Stripe Services Agreement](https://stripe.com/legal/ssa) section on "Preview Services" for more information. + ## Modules