From ffbbab7665a9acd6f7417a925ce3f27361f8f5bf Mon Sep 17 00:00:00 2001 From: Itay Brenner Date: Tue, 25 Nov 2025 13:42:09 -0300 Subject: [PATCH 1/5] chore: Add integrations documentation to developer-docs section --- develop-docs/INTEGRATIONS.md | 93 ++++++++++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 develop-docs/INTEGRATIONS.md diff --git a/develop-docs/INTEGRATIONS.md b/develop-docs/INTEGRATIONS.md new file mode 100644 index 0000000000..b12ce5dc92 --- /dev/null +++ b/develop-docs/INTEGRATIONS.md @@ -0,0 +1,93 @@ +# Integrations in other repositories + +We have identified that **SPM** downloads _all_ declared dependencies in a package, even if none the added actually added modules use them. + +This means that if `sentry-cocoa` declares dependencies like **CocoaLumberjack** or **SwiftLog**, _all_ downstream consumers download these libraries, even if they don’t use the corresponding integrations. + +To avoid forcing unnecessary dependencies on users, we already agreed to **remove integrations from the main repository**. + +However, maintaining multiple repositories introduces overhead for the team. + +### Goals + +- Avoid forcing users to download unused third-party dependencies. +- Keep integration code discoverable, maintainable, and testable. +- Minimize additional team workload. + +**Extras:** + +- Maintain flexibility in release schedules. + +### Agreed solution + +- **3: Keep all code in `sentry-cocoa`, but mirror releases into individual repositories** + + SPM users import the integration repos, but implementation lives in `sentry-cocoa`. + + Automated workflows push integration-specific code into dedicated repos during release. + + The idea comes from this repo: + + https://github.com/marvinpinto/action-automatic-releases + + Pros: + + - Source of truth stays in **one repository**. + - Development flow simpler (single CI, single contribution workflow). + - Users still get the benefit of **modular SPM dependencies**, without downloading everything. + - Mirrors how some SDKs manage platform-specific or optional components + + Cons: + + - Requires building a **custom mirroring release workflow**. + - Potential risk of divergence if mirror fails or is misconfigured. + - Release cadence may still be tied to `sentry-cocoa` unless new workflows are built. + - Requires tooling to ensure code in the main repo remains cleanly partitioned. + +### Discarded options: + +
+ See options +- **1: Move all integrations into new repository/ies** + + Two possible sub-variants: + + - Option A — One repository containing *all* integrations + - Option B — Group integrations by theme (e.g., logging integrations, feature-flag integrations) + + Pros: + + - Integrations _can_ (doesn't mind they should) have **independent release schedules** from `sentry-cocoa`. + - The main `sentry-cocoa` package remains **lean** and dependency-free. + - Users only download dependencies for the specific integrations they choose. + - The code remains centralized enough that cross-integration changes are simpler + + Cons: + + - Increases team workload due to more repositories to monitor. + - Requires many new repository setup. + - Cross-repo changes become harder. + - Risk of fragmentation: documentation, ownership, issue tracking become more distributed. + - Changes may require PRs across multiple repos. + +- **2: One integration per repository** + + Pros: + + - Users import only the exact integration they need. + - Extremely granular release management. + - Clean separation of concerns and dependency trees. + + Cons: + + - This is the **maximum possible repo overhead**. + - Cross-integration changes require coordinating multiple PRs. + - Significant overhead in monitoring issues and security alerts. + - Harder to keep documentation centralized or coherent. +- **4: Make Package.swift dynamic** + + This is a wild idea, but we have to double check if using `canImport(SwiftLog)` works for enabling the SwiftLog dependency. + + Needs a POC to confirm this is possible + +
From edc318c9dd7a9aa6649d74763f004037800e857e Mon Sep 17 00:00:00 2001 From: Itay Brenner Date: Fri, 28 Nov 2025 11:54:27 -0300 Subject: [PATCH 2/5] Move other options to Decisions.md --- develop-docs/DECISIONS.md | 81 ++++++++++++++++++++++++++++++++++++ develop-docs/INTEGRATIONS.md | 49 +--------------------- 2 files changed, 83 insertions(+), 47 deletions(-) diff --git a/develop-docs/DECISIONS.md b/develop-docs/DECISIONS.md index d276989529..0a28fa7324 100644 --- a/develop-docs/DECISIONS.md +++ b/develop-docs/DECISIONS.md @@ -479,3 +479,84 @@ Related links: - https://github.com/getsentry/sentry-cocoa/issues/6758 - https://github.com/getsentry/sentry-cocoa/pull/6873 + +## 3rd Party Library Integrations + +Date: November 28, 2025 +Contributors: @philprime, @philipphofmann, @itaybre + +### Background + +SPM downloads all declared dependencies in a package, even if none of the actually added modules use them. If `sentry-cocoa` declares dependencies like **CocoaLumberjack** or **SwiftLog**, all downstream consumers download these libraries, even if they don't use the corresponding integrations. + +### Agreed solution + +**Keep all code in `sentry-cocoa`, but mirror releases into individual repositories** + +SPM users import the integration repos, but implementation lives in `sentry-cocoa`. Automated workflows push integration-specific code into dedicated repos during release. + +The idea comes from this repo: https://github.com/marvinpinto/action-automatic-releases + +#### Pros + +- Source of truth stays in **one repository**. +- Development flow simpler (single CI, single contribution workflow). +- Users still get the benefit of **modular SPM dependencies**, without downloading everything. +- Mirrors how some SDKs manage platform-specific or optional components + +#### Cons + +- Requires building a **custom mirroring release workflow**. +- Potential risk of divergence if mirror fails or is misconfigured. +- Release cadence may still be tied to `sentry-cocoa` unless new workflows are built. +- Requires tooling to ensure code in the main repo remains cleanly partitioned. + +### Discarded options + +
+ See options + +#### Option 1: Move all integrations into new repository/ies + +Two possible sub-variants: + +- Option A — One repository containing _all_ integrations +- Option B — Group integrations by theme (e.g., logging integrations, feature-flag integrations) + +Pros: + +- Integrations _can_ (doesn't mean they should) have **independent release schedules** from `sentry-cocoa`. +- The main `sentry-cocoa` package remains **lean** and dependency-free. +- Users only download dependencies for the specific integrations they choose. +- The code remains centralized enough that cross-integration changes are simpler + +Cons: + +- Increases team workload due to more repositories to monitor. +- Requires many new repository setup. +- Cross-repo changes become harder. +- Risk of fragmentation: documentation, ownership, issue tracking become more distributed. +- Changes may require PRs across multiple repos. + +#### Option 2: One integration per repository + +Pros: + +- Users import only the exact integration they need. +- Extremely granular release management. +- Clean separation of concerns and dependency trees. + +Cons: + +- This is the **maximum possible repo overhead**. +- Cross-integration changes require coordinating multiple PRs. +- Significant overhead in monitoring issues and security alerts. +- Harder to keep documentation centralized or coherent. + +#### Option 3: Make Package.swift dynamic + +This is a wild idea, but we have to double check if using `canImport(SwiftLog)` works for enabling the SwiftLog dependency. + +Needs a POC to confirm this is possible + +
diff --git a/develop-docs/INTEGRATIONS.md b/develop-docs/INTEGRATIONS.md index b12ce5dc92..46c77731d9 100644 --- a/develop-docs/INTEGRATIONS.md +++ b/develop-docs/INTEGRATIONS.md @@ -44,50 +44,5 @@ However, maintaining multiple repositories introduces overhead for the team. - Release cadence may still be tied to `sentry-cocoa` unless new workflows are built. - Requires tooling to ensure code in the main repo remains cleanly partitioned. -### Discarded options: - -
- See options -- **1: Move all integrations into new repository/ies** - - Two possible sub-variants: - - - Option A — One repository containing *all* integrations - - Option B — Group integrations by theme (e.g., logging integrations, feature-flag integrations) - - Pros: - - - Integrations _can_ (doesn't mind they should) have **independent release schedules** from `sentry-cocoa`. - - The main `sentry-cocoa` package remains **lean** and dependency-free. - - Users only download dependencies for the specific integrations they choose. - - The code remains centralized enough that cross-integration changes are simpler - - Cons: - - - Increases team workload due to more repositories to monitor. - - Requires many new repository setup. - - Cross-repo changes become harder. - - Risk of fragmentation: documentation, ownership, issue tracking become more distributed. - - Changes may require PRs across multiple repos. - -- **2: One integration per repository** - - Pros: - - - Users import only the exact integration they need. - - Extremely granular release management. - - Clean separation of concerns and dependency trees. - - Cons: - - - This is the **maximum possible repo overhead**. - - Cross-integration changes require coordinating multiple PRs. - - Significant overhead in monitoring issues and security alerts. - - Harder to keep documentation centralized or coherent. -- **4: Make Package.swift dynamic** - - This is a wild idea, but we have to double check if using `canImport(SwiftLog)` works for enabling the SwiftLog dependency. - - Needs a POC to confirm this is possible - -
+> [!NOTE] +> For other options that were considered, see the [3rd Party Library Integrations decision in DECISIONS.md](DECISIONS.md#3rd-party-library-integrations). From 16dbf4bd360533778fa6782ed025e6c3cf9706f4 Mon Sep 17 00:00:00 2001 From: Itay Brenner Date: Fri, 28 Nov 2025 11:59:05 -0300 Subject: [PATCH 3/5] Add more details regarding folder structure --- develop-docs/INTEGRATIONS.md | 48 +++++++++++++++++++++++++++++++++--- 1 file changed, 45 insertions(+), 3 deletions(-) diff --git a/develop-docs/INTEGRATIONS.md b/develop-docs/INTEGRATIONS.md index 46c77731d9..301736a6e0 100644 --- a/develop-docs/INTEGRATIONS.md +++ b/develop-docs/INTEGRATIONS.md @@ -1,10 +1,12 @@ -# Integrations in other repositories +# 3rd Party Library Integrations in Other Repositories + +This document outlines our approach to managing integrations with **3rd party libraries** (such as CocoaLumberjack, SwiftLog, etc.). We have identified that **SPM** downloads _all_ declared dependencies in a package, even if none the added actually added modules use them. -This means that if `sentry-cocoa` declares dependencies like **CocoaLumberjack** or **SwiftLog**, _all_ downstream consumers download these libraries, even if they don’t use the corresponding integrations. +This means that if `sentry-cocoa` declares dependencies like **CocoaLumberjack** or **SwiftLog**, _all_ downstream consumers download these libraries, even if they don't use the corresponding integrations. -To avoid forcing unnecessary dependencies on users, we already agreed to **remove integrations from the main repository**. +To avoid forcing unnecessary 3rd party dependencies on users, we already agreed to **remove the integrations from the main Package.swift on on this repository**. However, maintaining multiple repositories introduces overhead for the team. @@ -46,3 +48,43 @@ However, maintaining multiple repositories introduces overhead for the team. > [!NOTE] > For other options that were considered, see the [3rd Party Library Integrations decision in DECISIONS.md](DECISIONS.md#3rd-party-library-integrations). + +### Contributing moving forward + +All integration development will continue in the main `sentry-cocoa` repository, organized in dedicated subdirectories for clean CI isolation. + +#### Directory Structure + +Each integration will be self-contained in `3rd-party-integration/INTEGRATION-NAME/` with: + +- `Sources/` - Integration source code +- `README.md` - Integration-specific documentation +- `Package.swift` - SPM package definition +- `*.podspec` - CocoaPods specification + +**Example:** + +``` +3rd-party-integration/ + ├── CocoaLumberjack/ + │ ├── Sources/ + │ ├── README.md + │ ├── Package.swift + │ └── SentryCocoaLumberjack.podspec + └── SwiftLog/ + ├── Sources/ + ├── README.md + ├── Package.swift + └── SentrySwiftLog.podspec +``` + +#### Release Process + +During each release, automated workflows will: + +1. Extract the integration directory contents +2. Push to the dedicated integration repository (e.g., `sentry-cocoa-swift-log`) +3. Create a tagged release matching the main SDK version + +> [!NOTE] +> This process will be automated via GitHub Actions. Initial releases may be handled manually while tooling is being developed. From 1b879875dd3f3d7df1559f499f94be0db1ddc03d Mon Sep 17 00:00:00 2001 From: Itay Brenner Date: Thu, 4 Dec 2025 10:53:30 -0300 Subject: [PATCH 4/5] remove pros and cons section, add tests directory to folder structure --- develop-docs/INTEGRATIONS.md | 15 +-------------- 1 file changed, 1 insertion(+), 14 deletions(-) diff --git a/develop-docs/INTEGRATIONS.md b/develop-docs/INTEGRATIONS.md index 301736a6e0..4b1c3e70ac 100644 --- a/develop-docs/INTEGRATIONS.md +++ b/develop-docs/INTEGRATIONS.md @@ -32,20 +32,6 @@ However, maintaining multiple repositories introduces overhead for the team. https://github.com/marvinpinto/action-automatic-releases - Pros: - - - Source of truth stays in **one repository**. - - Development flow simpler (single CI, single contribution workflow). - - Users still get the benefit of **modular SPM dependencies**, without downloading everything. - - Mirrors how some SDKs manage platform-specific or optional components - - Cons: - - - Requires building a **custom mirroring release workflow**. - - Potential risk of divergence if mirror fails or is misconfigured. - - Release cadence may still be tied to `sentry-cocoa` unless new workflows are built. - - Requires tooling to ensure code in the main repo remains cleanly partitioned. - > [!NOTE] > For other options that were considered, see the [3rd Party Library Integrations decision in DECISIONS.md](DECISIONS.md#3rd-party-library-integrations). @@ -58,6 +44,7 @@ All integration development will continue in the main `sentry-cocoa` repository, Each integration will be self-contained in `3rd-party-integration/INTEGRATION-NAME/` with: - `Sources/` - Integration source code +- `Tests/` - Test for the integration - `README.md` - Integration-specific documentation - `Package.swift` - SPM package definition - `*.podspec` - CocoaPods specification From b4695cbe21a63eb82a8661bb033fd4d842f40bd8 Mon Sep 17 00:00:00 2001 From: Itay Brenner Date: Thu, 4 Dec 2025 10:55:57 -0300 Subject: [PATCH 5/5] Update integration documentation to clarify folder naming conventions for dependencies --- develop-docs/INTEGRATIONS.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/develop-docs/INTEGRATIONS.md b/develop-docs/INTEGRATIONS.md index 4b1c3e70ac..9be1b42feb 100644 --- a/develop-docs/INTEGRATIONS.md +++ b/develop-docs/INTEGRATIONS.md @@ -53,18 +53,24 @@ Each integration will be self-contained in `3rd-party-integration/INTEGRATION-NA ``` 3rd-party-integration/ - ├── CocoaLumberjack/ + ├── SentryCocoaLumberjack/ │ ├── Sources/ │ ├── README.md │ ├── Package.swift │ └── SentryCocoaLumberjack.podspec - └── SwiftLog/ + └── SentrySwiftLog/ ├── Sources/ ├── README.md ├── Package.swift └── SentrySwiftLog.podspec ``` +Since SPM fails to resolve dependencies if the folder has the same name as one of the dependencies, we cannot use the library name as the folder name. +We will use the name of our dependency, for example: + +- `SentryCocoaLumberjack` for `CocoaLumberjack` +- `SentrySwiftLog` for `SwiftLog` + #### Release Process During each release, automated workflows will: