Skip to content

Update the Hermes >= 0.87 guide to match the current tooling - #1405

Open
fabriziocucci wants to merge 1 commit into
mainfrom
fabriziocucci/hermes-guide-087-updates
Open

Update the Hermes >= 0.87 guide to match the current tooling#1405
fabriziocucci wants to merge 1 commit into
mainfrom
fabriziocucci/hermes-guide-087-updates

Conversation

@fabriziocucci

Copy link
Copy Markdown
Collaborator

Cutting 0.88 today surfaced a set of places where the >= 0.87 section has drifted from the code it describes. Following it literally either does nothing, does the wrong thing silently, or fails.

What changed

1. The Hermes V1 branch is no longer hardcoded. 250829098.0.0-stable was named in six places. Hermes runs multiple trains now, 260318099.0.0-stable since #2101 on 2026-07-07, and the train a React Native release belongs to is whatever its branch already declares:

grep HERMES_VERSION_NAME packages/react-native/sdks/hermes-engine/version.properties

main and 0.88 are on 260318099.0.1, 0.87 is on 250829098.0.17. Following the guide as written on a 0.88 cut would have pinned 0.88-stable to a 250829098 version, downgrading it off the train main has been building against since 2026-07-23 (#57647) and desyncing the rn-tester Podfile.lock, which resolves the prebuilt Hermes pod at 260318099.0.1. Replaced with a "Which Hermes train?" section, the lookup above, and a current mapping table.

2. The bump command was wrong. The guide says:

./packages/react-native/scripts/hermes/bump-hermes-version.js -s <the_hermes_v1_tag>

-s was removed. Since the script's yargs call is not .strict(), it is silently discarded and the script falls back to fetching latest-v1 from NPM, so you get a version you did not type and no warning.

The documented -v fallback is broken too. It is declared as .option('v', {alias: 'version'}), so yargs treats it as its own built-in version flag:

$ ./packages/react-native/scripts/hermes/bump-hermes-version.js -v 260318099.0.1
1000.0.0

It prints packages/react-native/package.json's version and exits 0 without doing anything, so a wrapper sees success. Reproduced on yargs 17.7.2. The script needs .version(false); until then the no-argument path is the only one that works, and that is what the guide now documents.

3. Fixed the files to commit. The real filename is .hermesv1version, lowercase, not .hermesV1version. The copy-paste block had .hermesvesion and .hermesv1vesion, both typos, and included .hermesversion, which does not exist at >= 0.87, so the command fails. Also documented that package.json's hermes-compiler dependency is 0.0.0 on a freshly cut branch and that the bump is what fills it in, which is easy to miss and would otherwise ship in an rc.

4. Fixed step 5. It says bump HERMES_V1_VERSION_NAME on main. That key no longer exists there; main only has HERMES_VERSION_NAME since legacy Hermes was dropped. Also fixed the nested [...]([url](...)) markdown and the versions.properties typo.

5. Fixed the section lead-in, which said "Starting from React Native 0.83", copied from the dual-tag section below it. 0.83 is where the dual-tag scheme started, 0.87 is where it ended.

6. Flagged the CLI note in the header. rn-release-automator's cut-branch still prompts for both removed flags and git adds the nonexistent .hermesversion, so its Hermes step should not be used for >= 0.87. I will fix that separately in that repo.

Open question, deliberately not changed

Step 2 item 3 still says to leave Update latest-v1 unticked. That is right for a maintenance train, but the newest train owns the latest-v1 dist-tag, and latest-v1 is exactly what bump-hermes-version.js reads by default. So the rule is probably "tick on the current train, leave unticked on older ones", which is why #2152 made it opt-in. I did not want to encode a guess. @cipolleschi, could you confirm?

Same question for the train mapping itself: I inferred it from what the branches declare, not from anyone's stated intent.

The section had drifted from the code in several places, all of them hit
while cutting 0.88 today.

- The V1 release branch was hardcoded to 250829098.0.0-stable in six places.
  Hermes runs multiple trains now (260318099.0.0-stable since 2026-07-07),
  and the train a React Native release uses is whatever its branch declares
  in version.properties. Replaced the hardcoded name with a "Which Hermes
  train?" section plus a lookup, and a current mapping.
- bump-hermes-version.js was documented as taking `-s <tag>`. That flag was
  removed, the script takes no arguments today. The suggested `-v` fallback
  does not work either: it is declared as an alias of `version`, so yargs
  treats it as its own built-in version flag, prints the package version and
  exits without doing anything.
- The file to commit is .hermesv1version, not .hermesV1version, and the
  git add block had two typos (.hermesvesion, .hermesv1vesion) plus
  .hermesversion, which does not exist at >= 0.87 and fails the command.
- Step 5 said to bump HERMES_V1_VERSION_NAME on main. main only has
  HERMES_VERSION_NAME since legacy Hermes was dropped. Also fixed the nested
  markdown link and the versions.properties typo.
- The section opened with "Starting from React Native 0.83", copied from the
  dual-tag section below it.
- Noted in the header that rn-release-automator's Hermes step has not been
  updated for >= 0.87.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant