docs(release): match the release flow to models.ts (#1428)

The v0.10 rewrite removed every path and constant the version-tag
section named, so RELEASE.md now describes files that do not exist.

| RELEASE.md said | on `main` |
| --- | --- |
| `src/constants/modelUrls.ts` | gone, model URLs are in `src/models.ts`
|
| `src/constants/versions.ts` | gone (only under `legacy/`) |
| `LIB_VERSION` derives the tag | no such constant; tags are literals |
| `VERSION_TAG` = in-development | it is the **published** tag
(`resolve/v0.9.0`) |
| `PREVIOUS_VERSION_TAG` | does not exist; in-dev tag is
`NEXT_VERSION_TAG` |

The constants were renamed **and their meanings swapped**, which is the
dangerous part. Old step 2 says to make `VERSION_TAG` resolve to the
upcoming release; doing that today repoints all 288 already-shipped
model URLs onto an unpublished tag. That gets a caution block, not just
a correction.

Also in this PR:

- adapter package paths corrected (`packages/bare-resource-fetcher`,
`packages/expo-resource-fetcher`), plus a note that the publish workflow
reads the version from `packages/react-native-executorch/package.json`
- a new **HuggingFace artifacts** section. The flow depended on moving
release tags but never described it: publishing a `.pte` to a model repo
changes nothing for users until the tag moves, and model repos are
tagged independently of npm
- link to the model card standard in the spec repo

### Two things found while checking, not fixed here

Both are code, not docs, so they are left for separate PRs:

1. `packages/react-native-executorch/package.json` has `version: 0.0.0`
on `main`, and that is the field the publish workflow reads.
2. `.github/workflows/npm-publish.yml` calls
`./scripts/create-package.sh`, which does not exist on `main` (it is
still on `release/0.9`). A stable publish from `main` looks like it
would fail.

Author: msluszniak

RELEASE.md

@@ -2,36 +2,93 @@
 
 ## Version tag conventions
 
-Model URLs in `packages/react-native-executorch/src/constants/modelUrls.ts` are built from two constants in `versions.ts`:
+Model URLs in `packages/react-native-executorch/src/models.ts` are built from
+`BASE_URL` plus one of two tag constants defined in the same file:
 
-- `VERSION_TAG` — the **in-development** version (`resolve/v${LIB_VERSION}`). On `main` it points at the upcoming release; HuggingFace files under this tag may not be published until release day.
-- `PREVIOUS_VERSION_TAG` — the **latest published stable** release. Use for back-compat references that should follow the last shipped version.
+- `NEXT_VERSION_TAG` — the **in-development** tag (`resolve/v${MAJOR}.${NEXT_MINOR}.0`). Models
+  whose files are new or re-exported for the upcoming release point here. The
+  HuggingFace files under this tag may not exist until release day.
+- `VERSION_TAG` — the **latest published stable** tag (`resolve/v${MAJOR}.${MINOR}.0`). Models
+  whose files last changed in a shipped release stay here, so a release does not
+  repoint URLs whose artifacts did not change.
 
-Anything that must stay pinned to a specific older HuggingFace tag (e.g. deprecated aliases whose files were removed in a later release) should hardcode `resolve/v{MAJOR}.{MINOR}.0` directly in `modelUrls.ts` rather than reusing `PREVIOUS_VERSION_TAG`.
+Both are plain string literals; there is no `LIB_VERSION` to derive them from.
+
+> [!CAUTION]
+> These constants were renamed **and their meanings swapped** in v0.10. Before
+> that they lived in `src/constants/modelUrls.ts` / `src/constants/versions.ts`,
+> were derived from `LIB_VERSION`, and `VERSION_TAG` meant the *in-development*
+> tag while `PREVIOUS_VERSION_TAG` meant the published one. Today `VERSION_TAG`
+> is the **published** tag and `NEXT_VERSION_TAG` is the in-development one.
+> Editing `VERSION_TAG` by analogy with the old docs repoints every already
+> shipped model URL.
+
+Anything that must stay pinned to a specific older HuggingFace tag (e.g.
+deprecated aliases whose files were removed in a later release) should hardcode
+`resolve/v{MAJOR}.{MINOR}.0` directly in `models.ts` rather than reusing
+`VERSION_TAG`.
+
+## HuggingFace artifacts
+
+The library resolves models from HuggingFace by **tag**, so publishing a `.pte`
+to a model repo's `main` changes nothing for users until the release tag moves
+to the commit holding it. Model repos are tagged independently of npm; a repo
+only needs a tag move if its files changed this cycle.
+
+For every model repo whose files changed:
+
+1. Confirm the new files are on `main` in the repo, and that their checksums
+   match what was exported locally.
+2. Move the `v{MAJOR}.{MINOR}.0` tag to that commit (delete and recreate it).
+3. Read the tag back and confirm it resolves to the intended commit.
+
+Model card `README.md` files are generated from the repo tree and its
+`config.json` files; the standard and the generated/free section split are
+documented in
+[react-native-executorch-spec](https://huggingface.co/software-mansion/react-native-executorch-spec/blob/main/MODEL_CARD.md).
 
 ## Minor version release
 
 The release process of new minor version consists of the following steps:
 
-1. On `main`, confirm every model URL in `packages/react-native-executorch/src/constants/modelUrls.ts` that should ship in this release is already pointing at `VERSION_TAG` (the in-development tag) and that the matching files exist on [🤗 huggingface](https://huggingface.co/software-mansion) under the `v{MAJOR}.{MINOR}.0` tag.
-2. Make sure `LIB_VERSION` in `packages/react-native-executorch/src/constants/versions.ts` is `{MAJOR}.{MINOR}.0` so `VERSION_TAG` resolves to `resolve/v{MAJOR}.{MINOR}.0`.
-3. Ensure the `version` field of `package.json` is `{MAJOR}.{MINOR}.0` for the core package (`react-native-executorch`) and both adapter packages (`bare-resource-fetcher`, `expo-resource-fetcher`).
+1. On `main`, confirm every model URL in `packages/react-native-executorch/src/models.ts` that should ship in this release points at `NEXT_VERSION_TAG`, and that the matching files exist on [🤗 huggingface](https://huggingface.co/software-mansion) under the `v{MAJOR}.{MINOR}.0` tag. See [HuggingFace artifacts](#huggingface-artifacts) for moving those tags.
+2. Make sure `NEXT_VERSION_TAG` in `packages/react-native-executorch/src/models.ts` is `resolve/v{MAJOR}.{MINOR}.0`.
+3. Ensure the `version` field of `package.json` is `{MAJOR}.{MINOR}.0` for all four published packages:
+   - `packages/react-native-executorch` (core)
+   - `packages/bare-resource-fetcher`
+   - `packages/expo-resource-fetcher`
+   - `packages/react-native-executorch-webrtc`
+
+   The core publish workflow reads the version from
+   `packages/react-native-executorch/package.json`, so a wrong value there is
+   what gets published. The satellite workflow takes an explicit `version`
+   input instead.
+
+   The two fetcher adapters are still required at `{MAJOR}.{MINOR}.0`: the core
+   package ships the pre-0.10 API as `react-native-executorch/legacy`, and that
+   path throws at runtime unless the consumer passes an adapter from one of
+   them. Only the new API has a built-in fetcher.
 4. If any of the above required changes, commit them on `main` with the message 'Release v{MAJOR}.{MINOR}.0'.
 5. Create a new release branch `release/{MAJOR}.{MINOR}` from `main` and push it to the remote.
-6. Stability tests are performed on the release branch and all fixes to the new-found issues are pushed into the main branch and cherry-picked into the release branch. This allows for further development on the main branch without interfering with the release process.
-7. Once all tests are passed, tag the release branch with proper version tag `v{MAJOR}.{MINOR}.0` and run the following publish workflows:
+6. Confirm the native artifacts release the package resolves at install time
+   exists and is not a draft. `scripts/download-libs.js` downloads from the
+   GitHub Release tagged `v${nativeLibsVersion}-libs`, with `nativeLibsVersion`
+   pinned in the core `package.json`; if that release or any of its assets is
+   missing, every consumer's `postinstall` fails.
+7. Stability tests are performed on the release branch and all fixes to the new-found issues are pushed into the main branch and cherry-picked into the release branch. This allows for further development on the main branch without interfering with the release process.
+8. Once all tests are passed, tag the release branch with proper version tag `v{MAJOR}.{MINOR}.0` and run the following publish workflows. Both take a `dry-run` input; a dry run builds and packs without publishing, which is worth doing first since a failed publish cannot be taken back:
    - [npm publish (core)](https://github.com/software-mansion/react-native-executorch/actions/workflows/npm-publish.yml)
    - [npm publish satellite packages](https://github.com/software-mansion/react-native-executorch/actions/workflows/npm-publish-satellites.yml) — run once per satellite package, selecting it via the `package` input (`react-native-executorch-bare-resource-fetcher`, `react-native-executorch-expo-resource-fetcher`, `react-native-executorch-webrtc`)
-8. Create the release notes on GitHub.
-9. Bump `main` to the next development cycle in a single PR:
+9. Create the release notes on GitHub.
+10. Bump `main` to the next development cycle in a single PR:
    - Bump `version` in `package.json` to `{MAJOR}.{NEXT_MINOR}.0` for the core package and both adapter packages.
-   - Bump `LIB_VERSION` in `versions.ts` to `{MAJOR}.{NEXT_MINOR}.0` (this auto-bumps `VERSION_TAG`).
-   - Bump `PREVIOUS_VERSION_TAG` in `versions.ts` to `resolve/v{MAJOR}.{MINOR}.0` (the version that was just published).
+   - In `models.ts`, set `VERSION_TAG` to `resolve/v{MAJOR}.{MINOR}.0` (the version just published) and `NEXT_VERSION_TAG` to `resolve/v{MAJOR}.{NEXT_MINOR}.0`.
+   - Leave individual model URLs alone: those that shipped this cycle now resolve through `VERSION_TAG`, and only models re-exported next cycle move to `NEXT_VERSION_TAG`.
    - Commit with the message 'Bump version to v{MAJOR}.{NEXT_MINOR}.0'.
-10. Create versioned docs by running from repo root `(cd docs && yarn docs:version {MAJOR}.{MINOR}.x)` (the 'x' part is intentional and is not to be substituted). Also, make sure that all the links in `api-reference` are not broken.
-11. Create a PR with the updated docs.
-12. Update README.md with release video, if available.
-13. Update README.md links to release branch.
+11. Create versioned docs by running from repo root `(cd docs && yarn docs:version {MAJOR}.{MINOR}.x)` (the 'x' part is intentional and is not to be substituted). Also, make sure that all the links in `api-reference` are not broken.
+12. Create a PR with the updated docs.
+13. Update README.md with release video, if available.
+14. Update README.md links to release branch.
 
 ## Patch release