[RFC][Closed] Aligning CLI's versioning scheme with React Native

[huntie]

Background

React Native CLI is a separate project from React Native core, living in its own repository. At the same time, it is an integral component of using React Native (outside Expo) today, and is intricately tied to React Native features — offering interfaces to performing Android and iOS builds, parsing the react-native.config.js file in apps and libraries, and other supporting functionality.

This has made CLI changes sensitive in the past. For example, the @react-native/metro-config migration difficulties in 0.72 — where we merged a breaking change intended for 0.72 into CLI, which got immediately published to 0.71 users (ignoring semver in CLI, and breaking new installs for 24h).

Because of this, 0.72 was the first version of React Native where we moved to creating a major version of CLI dedicated to an RN release. Breaking changes could be made, until an aligned branch cut with React Native.

React Native version	CLI version
0.71	10.x
0.72	11.x
0.73 (incoming)	12.x
main	12.x ⚠️ We've forgotten / changed the pattern of incrementing this when the branch cut was made. 12.x now needs to support two major React Native versions.

Suggested model

Note

This RFC is resolved in react-native-community/cli@237481f. CLI released 13.x which conforms to the above pre-existing model.

Let's re-commit to the above major versioning with React Native, but align numerical versions to remove mental overhead.

The next version of React Native CLI (due to be 13.x, created when we made 0.73-stable in React Native), should be 74.0.0 (necessarily, a jump of major versions).

We will then unambiguously align versions going forward:

React Native version	CLI version
0.72	11.x
0.73	12.x
0.74 / main (incoming)	74.x ⬅️ Make this change now.
0.75 (future)	75.x
etc.

Benefits

• Removes confusion:
  • We have a cross-repo setup of components which make React Native work. An at-a-glance understanding of versions removes mental overhead for framework devs and integrators — and therefore reduces mistakes.
  • As above, we've forgotten to increment CLI this time when the branch cut for 0.73-stable was made.
• Stability
  • One major version of CLI aligns with one major version of React Native, simplifying the support matrix for CLI maintainers.
  • We originally made this call in 0.72 to avoid unwanted breakages to current versions (which will inevitably happen).
• Agility:
  • Targeting one React Native version at a time allows CLI to move fast and make breaking changes.
  • This also allows the freedom to patch past versions unambiguously (critically, without mandating the inclusion of all changes on main since).

I strongly believe these benefits outweigh the aspirational aim of following pure semver. We should align this and other @react-native-community/ projects where it makes sense.

[tido64]

Wasn't the whole point of moving @react-native-community/cli-plugin-metro into react-native to enable both to move independently? Why do we need to sync their versions?

[huntie]

Migrating @react-native-community/cli-plugin-metro has decoupled CLI from Metro changes, but does not decouple the rest of CLI from other functional changes to React Native in future.

These could be the structure of the template, API changes, or even changes to react-native.config.js across versions.

We also still observe breaking changes made to CLI (in these cases, inside 12.x) [1] [2], that have only been discovered when bumped in React Native and tested in the RC process [3] [4]. Defaulting to isolating new changes per React Native major is IMO a safe bet, as well as enabling the CLI project to boldly iterate.

[tido64]

I still don't understand how changing the versioning scheme is going to prevent any of those issues from happening? Wouldn't it be more productive to put effort into figuring out how we can decouple CLI from react-native? As things stand, CLI keeps getting new features but users can't get to them unless they also bump react-native. That makes no sense to me. The two should be independent of each other.

[huntie]

From our side (speaking myself), this proposal encourages stability and a predictable experience when users step up to a new version of React Native.

Your counterpoint is valid: CLI could aspire to ship incremental changes to users more frequently. But I believe this incurs an unwanted cost of 1/ supporting multiple versions off one branch — within an environment where React Native ships multiple breaking releases in a year. And 2/ making it hard to associate a given RN release with a CLI version at a glance.

A release branch in CLI per RN version doesn't prevent minor features to current or past releases, but adds friction, yes. But it's also worth weighing up if there would realistically be enough minor features that would want to be pushed (and communicated) to users that much more frequently than with each React Native release.

[szymonrybczak]

As things stand, CLI keeps getting new features but users can't get to them unless they also bump react-native. That makes no sense to me. The two should be independent of each other.

I must agree with this one, also we had a problem with init command on Linux machines. People couldn't create project. The fix in CLI landed at relevant branch on 13th Oct - react-native-community/cli#2096 (comment), and to use it users needed to wait for RN 0.72.7, which was released on 14th Nov.

[thymikee]

@szymonrybczak maybe that’s something that we could revisit in a reality where CLI is decoupled from Metro. I’d need to remember what was this change about, but it definitely fixed one or two things for users

[kelset]

How are things going to work when RN reached 1.0?

[huntie]

Definitely an open question! I think it's a problem for the future, presuming the package structure remains similar to how it is today.

The default approach is that CLI would switch to true semver upon 1.0. This might be CLI XX.0.0, and from there would ship minors and majors at its own cadence. There'd be no functional issue at all — just a high number with an interesting history.

[thymikee]

The CLI team can commit to have 1:1 matching between major RN versions and major CLI versions, even if there’s nothing breaking on our release. That’s zero overhead for us and will avoid confusion as to which version targets which versions of RN.

As to switching the version name, I don’t have a strong opinion, but I feel it’s not really necessary once the release crew team can be sure that for every branch cut there have to be next major version of the CLI targeting main. And we can commit to that as a part of release activities.

[huntie]

Sounds good, I'm happy to move forward this way if there isn't major support from the CLI team! Primary motivation is stability 👍🏻

[huntie]

Resolved in react-native-community/cli@237481f.