diff --git a/develop-docs/DECISIONS.md b/develop-docs/DECISIONS.md index f3b5855db9..997b1ec4a5 100644 --- a/develop-docs/DECISIONS.md +++ b/develop-docs/DECISIONS.md @@ -491,3 +491,81 @@ We also decided to streamline our integrations by reducing the number of package Related: - Fix for multiple files in Releases (stale for months): https://github.com/Carthage/Carthage/pull/3398 + +## 3rd Party Library Integrations + +### 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 new file mode 100644 index 0000000000..9be1b42feb --- /dev/null +++ b/develop-docs/INTEGRATIONS.md @@ -0,0 +1,83 @@ +# 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. + +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. + +### 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 + +> [!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 +- `Tests/` - Test for the integration +- `README.md` - Integration-specific documentation +- `Package.swift` - SPM package definition +- `*.podspec` - CocoaPods specification + +**Example:** + +``` +3rd-party-integration/ + ├── SentryCocoaLumberjack/ + │ ├── Sources/ + │ ├── README.md + │ ├── Package.swift + │ └── SentryCocoaLumberjack.podspec + └── 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: + +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.