Skip to content

Commit 4b6ec4f

Browse files
itaybreitaybre
authored
docs: Add integrations documentation to developer-docs section (#6902)
* chore: Add integrations documentation to developer-docs section * Move other options to Decisions.md * Add more details regarding folder structure * remove pros and cons section, add tests directory to folder structure * Update integration documentation to clarify folder naming conventions for dependencies
1 parent 4b6052d commit 4b6ec4f

File tree

2 files changed

+161
-0
lines changed

2 files changed

+161
-0
lines changed

‎develop-docs/DECISIONS.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -491,3 +491,81 @@ We also decided to streamline our integrations by reducing the number of package
491491
Related:
492492

493493
- Fix for multiple files in Releases (stale for months): https://github.com/Carthage/Carthage/pull/3398
494+
495+
## 3rd Party Library Integrations
496+
497+
### Background
498+
499+
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.
500+
501+
### Agreed solution
502+
503+
**Keep all code in `sentry-cocoa`, but mirror releases into individual repositories**
504+
505+
SPM users import the integration repos, but implementation lives in `sentry-cocoa`. Automated workflows push integration-specific code into dedicated repos during release.
506+
507+
The idea comes from this repo: https://github.com/marvinpinto/action-automatic-releases
508+
509+
#### Pros
510+
511+
- Source of truth stays in **one repository**.
512+
- Development flow simpler (single CI, single contribution workflow).
513+
- Users still get the benefit of **modular SPM dependencies**, without downloading everything.
514+
- Mirrors how some SDKs manage platform-specific or optional components
515+
516+
#### Cons
517+
518+
- Requires building a **custom mirroring release workflow**.
519+
- Potential risk of divergence if mirror fails or is misconfigured.
520+
- Release cadence may still be tied to `sentry-cocoa` unless new workflows are built.
521+
- Requires tooling to ensure code in the main repo remains cleanly partitioned.
522+
523+
### Discarded options
524+
525+
<details>
526+
<summary>See options</summary>
527+
528+
#### Option 1: Move all integrations into new repository/ies
529+
530+
Two possible sub-variants:
531+
532+
- Option A — One repository containing _all_ integrations
533+
- Option B — Group integrations by theme (e.g., logging integrations, feature-flag integrations)
534+
535+
Pros:
536+
537+
- Integrations _can_ (doesn't mean they should) have **independent release schedules** from `sentry-cocoa`.
538+
- The main `sentry-cocoa` package remains **lean** and dependency-free.
539+
- Users only download dependencies for the specific integrations they choose.
540+
- The code remains centralized enough that cross-integration changes are simpler
541+
542+
Cons:
543+
544+
- Increases team workload due to more repositories to monitor.
545+
- Requires many new repository setup.
546+
- Cross-repo changes become harder.
547+
- Risk of fragmentation: documentation, ownership, issue tracking become more distributed.
548+
- Changes may require PRs across multiple repos.
549+
550+
#### Option 2: One integration per repository
551+
552+
Pros:
553+
554+
- Users import only the exact integration they need.
555+
- Extremely granular release management.
556+
- Clean separation of concerns and dependency trees.
557+
558+
Cons:
559+
560+
- This is the **maximum possible repo overhead**.
561+
- Cross-integration changes require coordinating multiple PRs.
562+
- Significant overhead in monitoring issues and security alerts.
563+
- Harder to keep documentation centralized or coherent.
564+
565+
#### Option 3: Make Package.swift dynamic
566+
567+
This is a wild idea, but we have to double check if using `canImport(SwiftLog)` works for enabling the SwiftLog dependency.
568+
569+
Needs a POC to confirm this is possible
570+
571+
</details>

‎develop-docs/INTEGRATIONS.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# 3rd Party Library Integrations in Other Repositories
2+
3+
This document outlines our approach to managing integrations with **3rd party libraries** (such as CocoaLumberjack, SwiftLog, etc.).
4+
5+
We have identified that **SPM** downloads _all_ declared dependencies in a package, even if none the added actually added modules use them.
6+
7+
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.
8+
9+
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**.
10+
11+
However, maintaining multiple repositories introduces overhead for the team.
12+
13+
### Goals
14+
15+
- Avoid forcing users to download unused third-party dependencies.
16+
- Keep integration code discoverable, maintainable, and testable.
17+
- Minimize additional team workload.
18+
19+
**Extras:**
20+
21+
- Maintain flexibility in release schedules.
22+
23+
### Agreed solution
24+
25+
- **3: Keep all code in `sentry-cocoa`, but mirror releases into individual repositories**
26+
27+
SPM users import the integration repos, but implementation lives in `sentry-cocoa`.
28+
29+
Automated workflows push integration-specific code into dedicated repos during release.
30+
31+
The idea comes from this repo:
32+
33+
https://github.com/marvinpinto/action-automatic-releases
34+
35+
> [!NOTE]
36+
> For other options that were considered, see the [3rd Party Library Integrations decision in DECISIONS.md](DECISIONS.md#3rd-party-library-integrations).
37+
38+
### Contributing moving forward
39+
40+
All integration development will continue in the main `sentry-cocoa` repository, organized in dedicated subdirectories for clean CI isolation.
41+
42+
#### Directory Structure
43+
44+
Each integration will be self-contained in `3rd-party-integration/INTEGRATION-NAME/` with:
45+
46+
- `Sources/` - Integration source code
47+
- `Tests/` - Test for the integration
48+
- `README.md` - Integration-specific documentation
49+
- `Package.swift` - SPM package definition
50+
- `*.podspec` - CocoaPods specification
51+
52+
**Example:**
53+
54+
```
55+
3rd-party-integration/
56+
├── SentryCocoaLumberjack/
57+
│ ├── Sources/
58+
│ ├── README.md
59+
│ ├── Package.swift
60+
│ └── SentryCocoaLumberjack.podspec
61+
└── SentrySwiftLog/
62+
├── Sources/
63+
├── README.md
64+
├── Package.swift
65+
└── SentrySwiftLog.podspec
66+
```
67+
68+
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.
69+
We will use the name of our dependency, for example:
70+
71+
- `SentryCocoaLumberjack` for `CocoaLumberjack`
72+
- `SentrySwiftLog` for `SwiftLog`
73+
74+
#### Release Process
75+
76+
During each release, automated workflows will:
77+
78+
1. Extract the integration directory contents
79+
2. Push to the dedicated integration repository (e.g., `sentry-cocoa-swift-log`)
80+
3. Create a tagged release matching the main SDK version
81+
82+
> [!NOTE]
83+
> This process will be automated via GitHub Actions. Initial releases may be handled manually while tooling is being developed.

0 commit comments

Comments
 (0)