From 10064627ce9b20955c873c44665d58c214ac0eb9 Mon Sep 17 00:00:00 2001 From: Itay Brenner Date: Tue, 4 Aug 2026 17:13:40 -0300 Subject: [PATCH] docs: add mirroring documentation Document how code and releases are mirrored to downstream repositories, covering continuous sync via the mirror workflow and release-time distribution via Craft, including setup steps for new mirrors. --- develop-docs/MIRRORING.md | 58 +++++++++++++++++++++++++++++++++++++++ develop-docs/README.md | 1 + 2 files changed, 59 insertions(+) create mode 100644 develop-docs/MIRRORING.md diff --git a/develop-docs/MIRRORING.md b/develop-docs/MIRRORING.md new file mode 100644 index 0000000000..87e121ad16 --- /dev/null +++ b/develop-docs/MIRRORING.md @@ -0,0 +1,58 @@ +# Repository Mirroring + +sentry-cocoa mirrors code and release artifacts to downstream repositories so consumers can depend on them via SPM without pulling unnecessary third-party dependencies. There are two distinct mechanisms: **continuous code sync** (on every push to main) and **release-time distribution** (via Craft). + +For the motivation behind this approach, see [INTEGRATIONS.md](INTEGRATIONS.md) and [DECISIONS.md (decision #31)](DECISIONS.md#3rd-party-library-integrations). + +## Downstream Repositories + +| Source in sentry-cocoa | Downstream repo | Continuous sync | Release (Craft) | +| ----------------------------------------------- | ---------------------------------------- | --------------- | --------------- | +| `3rd-party-integrations/SentrySwiftLog/` | `getsentry/sentry-apple-swift-log` | yes | yes | +| `3rd-party-integrations/SentryCocoaLumberjack/` | `getsentry/sentry-apple-cocoalumberjack` | yes | yes | +| `3rd-party-integrations/SentryPulse/` | `getsentry/sentry-apple-pulse` | yes | yes | +| `3rd-party-integrations/SentrySwiftyBeaver/` | `getsentry/sentry-apple-swiftybeaver` | yes | yes | +| `distribution/apple-binaries/` | `getsentry/sentry-apple-binaries` | no | yes | + +## Continuous Code Sync + +**Workflow:** [`.github/workflows/mirror-3rd-party-integrations.yml`](../.github/workflows/mirror-3rd-party-integrations.yml) + +Triggers on every push to `main` that touches `3rd-party-integrations/**`. For each integration in the matrix: + +1. Checks out sentry-cocoa and the downstream repo. +2. Wipes the downstream repo (except `.git`). +3. Copies the integration directory contents plus root `LICENSE.md`. +4. Commits as `sentry-mobile-updater[bot]` and pushes. + +This keeps downstream repos up to date between releases, so consumers on the `main` branch always have the latest code. + +### Authentication + +The workflow uses the **sentry-mobile-updater** GitHub App (`SENTRY_DEPENDENCY_UPDATER_GITHUB_APP_ID` / `SENTRY_DEPENDENCY_UPDATER_GITHUB_APP_PRIVATE_KEY`) to generate a scoped token for each downstream repo. + +## Release-Time Distribution (Craft) + +**Config:** [`.craft.yml`](../.craft.yml) + +During a release, the [release workflow](../.github/workflows/release.yml): + +1. Builds XCFrameworks. +2. Creates `.tgz` archives via [`scripts/create-apple-binaries-archive.sh`](../scripts/create-apple-binaries-archive.sh) and [`scripts/create-3rd-party-integration-archive.sh`](../scripts/create-3rd-party-integration-archive.sh). +3. Craft pushes each archive to its downstream repo on the `main` branch and creates a Git tag matching the release version. + +Craft authenticates via the GitHub org's own rules — no additional repo-level setup is needed for release pushes. + +## Adding a New Downstream Mirror + +### For 3rd-party integrations + +1. **Create the downstream repo** under `getsentry/` (e.g., `getsentry/sentry-apple-`). +2. **Allow sentry-mobile-updater** — in the downstream repo, go to `https://github.com/getsentry//settings/rules/` and add `sentry-mobile-updater` to the allowed apps section in the branch ruleset. This is required for the continuous sync workflow to push commits. +3. **Add to the mirror workflow matrix** in [`.github/workflows/mirror-3rd-party-integrations.yml`](../.github/workflows/mirror-3rd-party-integrations.yml). +4. **Add a Craft target** in [`.craft.yml`](../.craft.yml) with a `commit-on-git-repository` entry matching the archive name. +5. **Add the archive mapping** in [`scripts/create-3rd-party-integration-archive.sh`](../scripts/create-3rd-party-integration-archive.sh). + +### For binary distribution repos (e.g., sentry-apple-binaries) + +Only a Craft target is needed — there is no continuous sync for binary artifacts. Craft authenticates through the GitHub org's rules, so no additional repo-level permission changes are required. diff --git a/develop-docs/README.md b/develop-docs/README.md index 5172f60276..f5b22a69ef 100644 --- a/develop-docs/README.md +++ b/develop-docs/README.md @@ -9,6 +9,7 @@ This is a collection of documents that can help you develop for the SentrySDK. - TEST.md: unit testing, UI testing and static/runtime analysis - BUILD.md: how we configure and build our SDK deliverables - RELEASE.md: our release processes and best practices +- MIRRORING.md: how code and releases are mirrored to downstream repositories - OBJC-LOAD-AND-LINKING.md: how Objective-C +load interacts with build configurations and distribution formats - SDK_HISTORY.md: historical context and FAQ for the SDK - [Language Trends Report](https://getsentry.github.io/sentry-cocoa/language-trends.html): interactive chart of the repository's language breakdown over time, updated on every merge to main via GitHub Pages