docs: fix stale release/build docs and rename guide to RELEASING.md (#1285)

Rename wiki/release.md -> root RELEASING.md to match the convention used
across the other Segment SDK repos (analytics-swift, -kotlin, -next), and
update its references in CONTRIBUTING.md and wiki/devbox.md.

CONTRIBUTING.md:
- Replace nonexistent `yarn bootstrap` with `devbox shell` / `yarn install`
- `yarn typescript` -> `yarn typecheck` (script was renamed)
- Replace removed `yarn e2e ...` commands with the Devbox/Detox flow in the
  example workspaces; fix `/example/` paths to examples/AnalyticsReactNativeExample
- Release section: name the actual `Release` workflow (was `Publish`) and its
  dry-run/beta/production types

RELEASING.md (moved from wiki/release.md):
- Drop the nonexistent `--config=shells/devbox-fast.json` flag from the
  sync-versions and release-dry-run commands (scripts live in root devbox.json)

wiki/devbox.md:
- Rewrite to reflect that Android/iOS SDK, emulator/simulator, and device
  management moved into the segment-integrations/mobile-devtools Devbox plugins
  consumed by the example workspaces; the root env is now build/test/release only
- Remove dead references to nix/, shells/, and examples/E2E/
- Correct the Releases note: npm publishing uses OIDC trusted publishing, not NPM_TOKEN

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: abueide

CONTRIBUTING.md

@@ -15,14 +15,20 @@ React Native requires different versions of the tools/languages you might be usi
 
 ## Development workflow
 
-To get started with the project, run `yarn bootstrap` in the root directory to install the required dependencies for each package:
+To get started with the project, install the dependencies for each package. The recommended path is to enter the Devbox shell, whose init hook runs `yarn install` for you (see [wiki/devbox.md](/wiki/devbox.md)):
 
 ```sh
-yarn bootstrap
+devbox shell
 ```
 
-While developing, you can run the [example app](/example/) to test your changes.
-code
+If you are not using Devbox, install dependencies directly with:
+
+```sh
+yarn install
+```
+
+While developing, you can run the [example app](/examples/AnalyticsReactNativeExample/) to test your changes.
+
 To start the packager:
 
 ```sh
@@ -44,7 +50,7 @@ yarn example ios
 Make sure your code passes TypeScript and ESLint. Run the following to verify:
 
 ```sh
-yarn typescript
+yarn typecheck
 yarn lint
 ```
 
@@ -60,24 +66,25 @@ Remember to add tests for your change if possible. Run the unit tests by:
 yarn test
 ```
 
-The are also end-to-end tests. First you will have to build the app and then run the tests:
+There are also end-to-end tests, driven by Detox through Devbox in the example workspaces under `examples/` (`e2e-latest` and `e2e-compat`). The E2E scripts live in each example's `devbox.json`, not the repo root. From an example directory you build, then test:
 
-```
-# Start the server (*note there's a separate e2e command*)
-yarn e2e start:e2e
+```sh
+cd examples/e2e-latest   # or examples/e2e-compat
 
 # iOS
-yarn e2e e2e:build:ios
-yarn e2e e2e:test:ios
+devbox run build:ios
+devbox run test:ios
 
 # Android
-yarn e2e e2e:build:android
-yarn e2e e2e:test:android
+devbox run build:android
+devbox run test:android
 ```
 
-To edit the Objective-C / Swift files, open `example/ios/AnalyticsReactNativeExample.xcworkspace` in XCode and find the source files at `Pods > Development Pods > @segment/analytics-react-native`.
+See [wiki/e2e/setup.md](/wiki/e2e/setup.md) for the full setup, and `.github/workflows/e2e-tests.yml` for how CI orchestrates these runs.
+
+To edit the Objective-C / Swift files, open `examples/AnalyticsReactNativeExample/ios/AnalyticsReactNativeExample.xcworkspace` in XCode and find the source files at `Pods > Development Pods > @segment/analytics-react-native`.
 
-To edit the Kotlin files, open `example/android` in Android studio and find the source files at `segmentanalyticsreactnative` under `Android`.
+To edit the Kotlin files, open `examples/AnalyticsReactNativeExample/android` in Android studio and find the source files at `segmentanalyticsreactnative` under `Android`.
 
 ### Commit message convention
 
@@ -102,21 +109,20 @@ Our pre-commit hooks verify that the linter and tests pass when committing.
 
 ### Scripts
 
-The `package.json` file contains various scripts for common tasks:
+The root `package.json` file contains various scripts for common tasks:
 
-- `yarn bootstrap`: setup project by installing all dependencies and pods.
-- `yarn typescript`: type-check files with TypeScript.
+- `yarn typecheck`: type-check files with TypeScript.
 - `yarn lint`: lint files with ESLint.
 - `yarn test`: run unit tests with Jest.
+- `yarn build`: build all public workspaces.
 - `yarn example start`: start the Metro server for the example app.
 - `yarn example android`: run the example app on Android.
 - `yarn example ios`: run the example app on iOS.
-- `yarn e2e e2e:build:ios`: builds the e2e app using detox
-- `yarn e2e e2e:test:ios`: runs the e2e on a simulator(headless if not ran manually)
-- `yarn e2e e2e:build:android`: builds the e2e app using detox
-- `yarn e2e e2e:test:android`: runs the e2e on an emulator
-- `yarn e2e ios:deeplink`: opens the ios app via deep link (example app must already be installed)
-- `yarn e2e android:deeplink`: opens the Android app via deep link (example app must already be installed)
+
+End-to-end tests are run from the example workspaces via Devbox (see above and `examples/<example>/devbox.json`):
+
+- `devbox run build:ios` / `devbox run test:ios`: build and run the iOS E2E suite with Detox.
+- `devbox run build:android` / `devbox run test:android`: build and run the Android E2E suite with Detox.
 
 ### Sending a pull request
 
@@ -132,10 +138,10 @@ When you're sending a pull request:
 
 ## Release
 
-Release is automated in GHA. By default `yarn release` won't let you trigger a release from your personal computer.
+Release is automated in GitHub Actions. By default `yarn release` won't let you trigger a release from your personal computer.
 
-To trigger a release go to Actions. Select the `Publish` workflow and trigger a new job.
+To trigger a release, go to Actions, select the `Release` workflow, click "Run workflow", and choose a release type (`dry-run`, `beta`, or `production`).
 
-Automatically the workflow will analyze the commits, bump versions, create changesets, build and release to NPM the packages that need so.
+The workflow analyzes the conventional-commit history, bumps versions, builds, and publishes to npm the packages that need it. See [RELEASING.md](/RELEASING.md) for the full release guide (release types, beta/fix-candidate flow, and version syncing).
 
-The CI/CD is automated using [semantic-release](https://github.com/semantic-release/semantic-release).
+The CI/CD is automated using [semantic-release](https://github.com/semantic-release/semantic-release) and [multi-semantic-release](https://github.com/qiwi/multi-semantic-release).

wiki/release.md RELEASING.mdwiki/release.md renamed to RELEASING.md

@@ -19,4 +19,4 @@ Internal documentation for analytics-react-native contributors.
 
 ## Release
 
-- [Release Guide](release.md) — Cutting releases with semantic-release and multi-semantic-release
+- [Release Guide](../RELEASING.md) — Cutting releases with semantic-release and multi-semantic-release

wiki/README.md

@@ -1,70 +1,101 @@
 # Devbox
 
-This repo uses [Devbox](https://www.jetify.com/devbox/) for reproducible builds. Each example app has its own `devbox.json` that pins Node.js, JDK, and build tools via Nix, with the [`mobile-devtools`](https://github.com/segment-integrations/mobile-devtools) plugin providing emulator/simulator management.
+This repo uses [Devbox](https://www.jetify.com/devbox/docs/) to provide reproducible, project-local development environments. Devbox uses Nix under the hood to pin tool versions so everyone gets the same setup. You don't need to know Nix to use it.
 
-The root `devbox.json` is for library development only (linting, building, testing, releasing). E2E builds and device management live in the per-app configs.
+There are two tiers of Devbox environment in this repo:
 
-## Getting started
+1. **Root environment** (`devbox.json` at the repo root) — a lean environment for building, testing, linting, formatting, and releasing the library packages. It does **not** provision the Android SDK, emulators, or iOS simulators.
+2. **Example/E2E environments** (`examples/e2e-latest/devbox.json`, `examples/e2e-compat/devbox.json`) — full mobile build + device environments for running the Detox end-to-end suites. These provision the Android and iOS toolchains via the shared [mobile-devtools](https://github.com/segment-integrations/mobile-devtools) Devbox plugins.
 
-1. Install Devbox: https://www.jetify.com/devbox/docs/installing_devbox/
-2. Navigate to an example app directory:
-   ```bash
-   cd examples/e2e-compat  # or e2e-latest
-   ```
-3. Run commands via `devbox run`:
-   ```bash
-   devbox run install
-   devbox run install:pods   # iOS only
-   devbox run build:android
-   devbox run build:ios
-   ```
+## Root environment
 
-## Per-app configuration
+Enter it from the repo root with `devbox shell`. The init hook sets `PROJECT_ROOT`, adds `node_modules/.bin` to `PATH`, runs `yarn install` if dependencies are missing, prebuilds `packages/core/src/info.ts`, and installs the Husky git hooks.
 
-Each example app's `devbox.json` defines:
+### Packages
 
-- **Packages**: Node.js, Yarn, JDK, and optional extras (watchman, etc.)
-- **Plugin**: `mobile-devtools` from `github:segment-integrations/mobile-devtools?dir=plugins/react-native&ref=main`
-- **Environment variables**: SDK versions, artifact paths, cmake version
-- **Scripts**: `install`, `install:pods`, `build:android`, `build:ios`, `test:android`, `test:ios`
+`cocoapods`, `nodejs` 22, `yarn-berry`, `jq`, `treefmt`, `nixfmt`, `shfmt`.
 
-### Plugin-provided scripts
+### Scripts
 
-The `mobile-devtools` plugin adds device management commands:
+Run with `devbox run <script>`:
 
-| Script               | Description                 |
-| -------------------- | --------------------------- |
-| `start:emu [device]` | Start Android emulator      |
-| `stop:emu`           | Stop Android emulator       |
-| `start:sim [device]` | Start iOS simulator         |
-| `stop:sim`           | Stop iOS simulator          |
-| `start:android`      | Build + deploy to emulator  |
-| `start:ios`          | Build + deploy to simulator |
+- `build` — build all public workspaces (`yarn build`).
+- `test` — run unit tests (`yarn test`).
+- `typecheck` — type-check (`yarn typecheck`).
+- `lint` / `format` / `format-check` — ESLint and treefmt.
+- `check` — runs lint, format-check, build, typecheck, and test in sequence (the local equivalent of CI).
+- `clean` — clean build artifacts and `node_modules`.
+- `release` / `release-dry-run` — run multi-semantic-release (see [RELEASING.md](../RELEASING.md)); these are invoked by the `Release` GitHub workflow, not run locally as a rule.
+- `sync-versions` — reconcile `package.json` versions with what was published to npm (`scripts/sync-versions.sh`).
+- `update-apps` — refresh the example apps' dependencies against the workspace.
+- `ci:install` / `ci:commitlint` — used by CI.
 
-## Root devbox.json
+## Example / E2E environments
 
-The root config is for library development and CI:
+The Detox E2E suites live in the example workspaces:
 
-| Script          | Description                           |
-| --------------- | ------------------------------------- |
-| `build`         | Build all packages                    |
-| `test`          | Run unit tests                        |
-| `lint`          | Run ESLint                            |
-| `typecheck`     | Run TypeScript type checking          |
-| `format`        | Format with prettier                  |
-| `release`       | Publish packages via semantic-release |
-| `sync-versions` | Sync package.json versions with npm   |
+- `examples/e2e-latest` — newest supported React Native.
+- `examples/e2e-compat` — minimum supported React Native.
+
+Each `devbox.json` includes the React Native plugin from mobile-devtools:
+
+```json
+"include": [
+  "github:segment-integrations/mobile-devtools?dir=plugins/react-native&ref=main"
+]
+```
+
+The React Native plugin composes the Android and iOS plugins, which provide the emulator/simulator lifecycle and device management. Project-local device definitions and lock files are committed under each example's `devbox.d/` directory (`segment-integrations.mobile-devtools.android/` and `…ios/`, with `devices/min.json` and `devices/max.json` plus their `.lock` files), so the SDK/device configuration is reviewable in PRs and reproducible across machines.
+
+### Running E2E
+
+From an example directory:
+
+```sh
+cd examples/e2e-latest   # or examples/e2e-compat
+
+# iOS
+devbox run build:ios
+devbox run test:ios
+
+# Android
+devbox run build:android
+devbox run test:android
+```
+
+The `build:*` scripts are defined locally in each example's `devbox.json`; `test:*` boot a simulator/emulator (via the plugin's `start:sim` / `start:emu`) and then run Detox. See [wiki/e2e/setup.md](e2e/setup.md) for the shared test architecture and [.github/workflows/e2e-tests.yml](../.github/workflows/e2e-tests.yml) for how CI orchestrates the matrix.
+
+### Plugin-provided commands
+
+The mobile-devtools React Native plugin exposes device/build helpers that the example scripts build on, including:
+
+- **Android:** `devbox run start:emu`, `devbox run stop:emu`, `devbox run reset:emu`, `devbox run start:android` (build + install + launch).
+- **iOS:** `devbox run start:sim`, `devbox run stop:sim`, `devbox run start:ios` (build + install + launch).
+- **Metro:** `devbox run start:metro`, `devbox run stop:metro`.
+- **Diagnostics:** `devbox run doctor`, `devbox run verify:setup`.
+
+For the full command list, configurable env vars, and device-definition/lock-file workflow, see the plugin docs in the [mobile-devtools](https://github.com/segment-integrations/mobile-devtools) repo (`plugins/react-native/README.md` and `REFERENCE.md`, plus the `plugins/android` and `plugins/ios` READMEs).
+
+### Configuring SDK / device versions
+
+SDK levels and build tools are set via env vars in the example's `devbox.json` (e.g. `ANDROID_COMPILE_SDK`, `ANDROID_BUILD_TOOLS_VERSION`, `CMAKE_VERSION`, `ANDROID_APP_APK`, `IOS_APP_ARTIFACT`). Device targets are defined in the `devbox.d/.../devices/*.json` files and pinned by the adjacent `.lock` files; after editing a device definition, regenerate its lock file per the plugin docs. The Detox device wiring lives in each example's `.detoxrc.js`.
 
 ## iOS build notes
 
+iOS uses the host Xcode toolchain — there is no Nix-provisioned iOS SDK. Make sure full Xcode is installed (Command Line Tools alone are not enough for `simctl`), the right toolchain is selected (`xcode-select --print-path`), and you have accepted the Xcode license. On macOS, `devbox shell` injects Nix toolchain variables; the plugin's init hooks re-select the system toolchain so Xcode builds work.
+
 Both example apps use a two-step iOS build to avoid Metro resolution issues in the monorepo:
 
-1. `RCT_NO_LAUNCH_PACKAGER=1 SKIP_BUNDLING=1 xcodebuild ...` — builds native binary without bundling JS or spawning Metro
-2. `react-native bundle ...` — creates the JS bundle directly into the .app
+1. `RCT_NO_LAUNCH_PACKAGER=1 SKIP_BUNDLING=1 xcodebuild ...` — builds the native binary without bundling JS or spawning Metro.
+2. `react-native bundle ...` — creates the JS bundle directly into the `.app`.
 
 `RCT_NO_LAUNCH_PACKAGER=1` prevents the Xcode "Start Packager" build phase from opening a Metro terminal during release builds.
 
 ## Android build notes
 
-- `e2e-compat` (RN 0.72): Standard `./gradlew assembleRelease`
-- `e2e-latest` (RN 0.84): Runs `generateCodegenArtifactsFromSchema --rerun-tasks` before assembly (required for New Architecture)
+- `e2e-compat` (RN 0.72): standard `./gradlew assembleRelease`.
+- `e2e-latest` (RN 0.84): runs `generateCodegenArtifactsFromSchema --rerun-tasks` before assembly (required for the New Architecture).
+
+## Releases
+
+`devbox run release` (root environment) runs `yarn install --immutable`, `yarn build`, and `yarn release` (multi-semantic-release). It is invoked by the production/beta jobs of the `Release` GitHub workflow. Publishing to npm uses OIDC trusted publishing with provenance — there is **no** `NPM_TOKEN`; the workflow passes only `GH_TOKEN` (`github.token`) for GitHub releases. See [RELEASING.md](../RELEASING.md) for the full release guide.