From ccc7cb1fae5d191723b15ee8194719187f0faacc Mon Sep 17 00:00:00 2001
From: Doberjohn <johnfanidis@gmail.com>
Date: Thu, 29 Oct 2026 14:34:49 +0200
Subject: [PATCH] chore: pass the release version through and infer the npm tag

The release script ran `release-it --only-version`. release-it 13.7.2 has
no such option and parses only --dry-run and --ci as boolean flags, so
`yarn release 6.0.0-alpha.1` took the version as the flag's value and
released the recommended bump instead: 6.0.0.

.release-it.json pinned npm.tag to "alpha" and github.preRelease to true.
A configured tag always wins, so every release, 6.0.0 included, would go
to the alpha tag as a GitHub prerelease and leave 5.15.3 on latest.

- Run plain `release-it`, so the version passed is the version released.
- Drop npm.tag and github.preRelease: release-it takes the tag from the
  prerelease id (alpha, beta, rc) or uses latest for a stable version,
  and marks prereleases on GitHub by itself.
- Create the GitHub release as a draft, so the example app pipeline
  (which runs when a release is published) waits until npm has the
  package.
- Rewrite "Publishing a release" in CONTRIBUTING.md to match.
---
 .release-it.json |  5 ++---
 CONTRIBUTING.md  | 18 +++++++++++++++---
 package.json     |  2 +-
 3 files changed, 18 insertions(+), 7 deletions(-)

diff --git a/.release-it.json b/.release-it.json
index 141b5d1193..bd70df14cf 100644
--- a/.release-it.json
+++ b/.release-it.json
@@ -4,12 +4,11 @@
     "tagName": "v${version}"
   },
   "npm": {
-    "publish": true,
-    "tag": "alpha"
+    "publish": true
   },
   "github": {
     "release": true,
-    "preRelease": true
+    "draft": true
   },
   "plugins": {
     "@release-it/conventional-changelog": {
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3e3fa7278f..99aef2a692 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -101,15 +101,27 @@ To preview the documentation, run `yarn docs dev` in the project root.
 
 ### Publishing a release
 
-We use [release-it](https://github.com/webpro/release-it) to automate our release. If you have publish access to the NPM package, run the following from the main branch to publish a new release:
+We use [release-it](https://github.com/webpro/release-it) to automate our release. If you have publish access to the NPM package, run the following from the main branch, always with the exact version you want to publish:
 
 ```sh
-yarn release
+yarn release 6.0.0-beta.0 --dry-run
+yarn release 6.0.0-beta.0
+```
+
+- Always pass the version. A bare `yarn release` applies the bump the commit history recommends, which can be a stable or major version you did not intend. npm never accepts the same version twice, so a wrong version cannot be taken back.
+- Start with the dry run. Before running it for real, check the compare range in the changelog heading it prints (for example `v6.0.0-alpha.0...v6.0.0-alpha.1`) and the `--tag` on the `npm publish` line.
+- The npm tag and the GitHub prerelease flag follow the version: `6.0.0-beta.0` is published under the `beta` tag as a GitHub prerelease, `6.0.0` under `latest` as a regular release.
+- The GitHub release is created as a draft. Once `npm publish` has succeeded, add the release notes and publish the draft:
+
+```sh
+gh release edit v6.0.0-beta.0 --notes-file notes.md --draft=false
 ```
 
 NOTE: You must have a `GITHUB_TOKEN` environment variable available. You can create a GitHub access token with the "repo" access [here](https://github.com/settings/tokens).
 
-Releases from main also deploy the example app via EAS. If there were no native code changes, it'll ship an OTA update.
+You also need to be logged in to npm with an account that can publish the package: check with `npm whoami`, and run `npm login` if it fails.
+
+Publishing the GitHub release also deploys the example app via EAS, so keep the release a draft until npm has the package. If there were no native code changes, it'll ship an OTA update.
 
 Otherwise, for stable releases:
 
diff --git a/package.json b/package.json
index c0c83323ee..11e2f3f411 100644
--- a/package.json
+++ b/package.json
@@ -40,7 +40,7 @@
     "test": "jest",
     "prepack": "bob build",
     "generate-mappings": "node ./scripts/generate-mappings.ts",
-    "release": "release-it --only-version",
+    "release": "release-it",
     "docs": "yarn --cwd docs",
     "example": "yarn --cwd example"
   },