# Contributing to React Native Brownfield ## Project setup Run `yarn` in the root of the repository to install all dependencies. Depending on your needs, you may need to install CocoaPods in the example React Native iOS app: `cd apps/RNApp/ios && pod install`. ## Contributing changes After contributing your changes, please make sure to add a [changeset](https://github.com/changesets/changesets) describing your changes. This will help us in publishing new versions. ### Pre-commit guard for brownfield-navigation This is a monorepo and the files inside `@callstack/brownfield-navigation` are auto-generated whenever `brownfield:package:*` is run. This is a desired behavior for the end user as these files will be inside the `node_modules`. However, since in this repo this package is symlinked, we see the changes in our git tree. These should not be committed by accident. A `pre-commit` guard blocks commits when those generated files are staged. If you need to intentionally commit those files (for an explicit update), bypass the guard for that commit: `SKIP_BROWNFIELD_NAVIGATION_CHECK=1 git commit -m "..."` ### Verifying a change Run the checks for the area you touched before opening a PR. CI runs the same ones, so this catches most failures locally. | If you changed | Run | | --- | --- | | TS/JS in `packages/` | `yarn build`, `yarn lint`, `yarn typecheck` and `yarn test:packages`. The pre-commit hook already runs lint and typecheck on staged JS/TS files. | | `scripts/` | `yarn test:scripts` | | JS in the example apps under `apps/` | `yarn test:apps` | | The `BrownfieldConfig` type | `yarn generate:schema`. The pre-commit hook regenerates `packages/cli/schema.json` and stages it. | | The Brownfield Gradle plugin (`gradle-plugins/react/brownfield`) | From that directory: `./gradlew detekt ktlintCheck test`, which is what CI runs. `yarn gradle-plugin:lint` also runs detekt, but its `ktlintFormat` rewrites files. | | Native iOS or Android code in a package | Build the affected example with its `build:example:*` script (see [Workspace scripts](#workspace-scripts)), then run the matching E2E with the [Local CI scripts](#local-ci-scripts). | | Anything in a published package | Add a changeset with `yarn changeset`. CI fails the PR without one (`changeset status`). | ## Publishing to npm We use [changesets](https://github.com/changesets/changesets) to version and publish packages. Contributors only add a changeset to their PR. CI does the rest. The release workflow (`.github/workflows/release.yml`) runs on every push to `main`: 1. A PR with a changeset is merged to `main`. 2. The workflow builds the packages, runs `yarn ci:version` (which bumps versions, updates changelogs and refreshes the lockfile), and opens or updates a PR titled `chore(release): version packages` with the result. 3. Merging the version PR runs the workflow again, and this time `yarn ci:publish` (`changeset publish`) publishes the new versions to npm. The packages listed in the `fixed` group in `.changeset/config.json` always share one version. A changeset for any of them bumps all of them. CI has no npm token. It publishes through [npm trusted publishing](https://docs.npmjs.com/trusted-publishers), which uses the workflow's OIDC identity (`id-token: write`). Trusted publishing requires npm CLI 11.5.1 or later and Node 22.14.0 or later on the runner. To confirm a release went through CI, check that `npm view @ _npmUser` shows `GitHub Actions`. ### Publishing a new package for the first time A trusted publisher can only be configured for a package that already exists on npm. A brand-new package therefore needs one manual publish by a maintainer. After that, CI publishes it like every other package. > [!IMPORTANT] > Publish the new package manually and configure its trusted publisher before merging the PR that adds it. Otherwise the next release tries to publish a package that CI has no permission for, and the release fails. The order is: manual publish, configure the trusted publisher, merge the PR, then let the next version PR publish the package. 1. Use an npm account (personal or a Callstack one) with two-factor authentication enabled. 2. Ask a Callstack npm org admin to add your npm username to the `@callstack` org. npm sends the invitation by email; accept it. The default `developer` role is enough to publish a new package under the scope. 3. Log in and check the account: ```sh npm login npm whoami ``` `npm login` prints a URL instead of asking for a password. Finish the login, including two-factor authentication, in the browser. 4. Prepare the package on the PR branch: - Set `version` in its `package.json` to the version the rest of the fixed group uses (see `packages/react-native-brownfield/package.json`). - Add the package name to the `fixed` group in `.changeset/config.json`. - Make sure `publishConfig.access` is `public`. 5. Build all packages from the repository root: ```sh yarn build ``` 6. Pack the package. Use `yarn` here, not `npm`: dependencies between workspace packages use `workspace:^`, and `npm publish` run inside the package folder would publish that range literally. `yarn pack` replaces it with real versions. ```sh yarn workspace pack ``` This writes `package.tgz` into the package folder. 7. Inspect the tarball before publishing. Check the file list, and check that `package/package.json` inside it has no `workspace:` ranges: ```sh tar -tzf packages//package.tgz tar -xzOf packages//package.tgz package/package.json | grep workspace: ``` The second command should print nothing. Optionally, run `npm publish packages//package.tgz --dry-run`. 8. Publish the tarball: ```sh npm publish packages//package.tgz ``` Run this in an interactive terminal. npm prints an authentication URL and waits with "Press ENTER to open in the browser". Approve the publish there and npm finishes on its own. In a non-interactive shell, such as a command run by an AI agent, npm can't wait and fails with `EOTP`. Nothing is published in that case, so run the command again in a regular terminal. A published version can't be published again, even after unpublishing. Double-check the version before running this. 9. Check that the version is live: ```sh npm view versions ``` npm reports "Your package is being processed and may take a few minutes to become available". Until processing ends, the registry only lists a `0.0.0-stage` placeholder. The real version showed up after about two minutes the first time we did this. 10. Delete `package.tgz`. Never commit it. Example: `@callstack/create-react-native-brownfield` lives in `packages/create-react-native-brownfield` and was first published by hand as `5.1.1`. ### Configuring the trusted publisher Do this once per package, right after its first manual publish. The other packages in the repo already have the same connection, so you can compare with any of them (for example `https://www.npmjs.com/package/@callstack/brownfield-navigation/access`). 1. Open the settings page of the new package: `https://www.npmjs.com/package//access`. Make sure it is the new package and not an existing one. Adding the same connection to a package that already has it fails with "a trusted publisher configuration that a token could also match already exists for this package". 2. Under **Trusted Publisher**, select **GitHub Actions** and fill in the form: - **Label**: leave empty. - **Organization or user**: `callstack` - **Repository**: `react-native-brownfield`. This is the GitHub repository that publishes, not the npm package name. - **Workflow filename**: `release.yml` - **Environment name**: leave empty. The release workflow doesn't use one. - **Allowed actions**: check **Allow npm publish**, leave **Allow npm dist-tag** unchecked. `npm stage publish` is always allowed. The provider and required fields can't be edited after saving. To fix a typo, delete the connection and create a new one. 3. Click **Set up connection**. The card should show `callstack/react-native-brownfield`, `release.yml` and the permissions **npm publish** and **npm stage publish**. 4. Under **Publishing access**, select **Require two-factor authentication and disallow bypass 2fa tokens (recommended)** and click **Update Package Settings**. Trusted publishing keeps working with this option. ## Scripts Root scripts run from the repository root with `yarn