Docs: clarify coupled gem/npm/lockfile steps when upgrading React on Rails Pro

[justin808]

Summary

The React on Rails / React on Rails Pro upgrade docs should explicitly call out that upgrading the Ruby gem is a coupled Ruby + JavaScript package upgrade. Agents and humans can otherwise update Gemfile / Gemfile.lock but miss the matching npm packages and yarn.lock / package-lock changes.

This came up while debugging shakacode/react-webpack-rails-tutorial#740. The first version of that upgrade bumped the Ruby and npm package manifests but did not update the JS lockfile; the current PR has the lockfile fix, but is separately blocked by the RC regression tracked in #3366.

Why this matters

For React on Rails Pro apps, these versions need to move together:

Gemfile:
  react_on_rails_pro

Gemfile.lock:
  react_on_rails_pro
  react_on_rails
  transitive Ruby dependencies such as jwt

package.json:
  react-on-rails-pro
  react-on-rails-pro-node-renderer
  sometimes react-on-rails-rsc, depending on the release

yarn.lock / package-lock.json / pnpm-lock.yaml:
  the matching npm package resolutions and transitive npm dependencies

There is also an easy-to-miss prerelease format difference:

Ruby gem version: 16.7.0.rc.0
npm package version: 16.7.0-rc.0

Without an explicit checklist, an automated coding agent can produce a PR that looks superficially correct but fails CI under frozen lockfile install.

Proposed docs addition

Add a small section to the upgrade docs, release notes checklist, and/or Pro/RSC docs along these lines:

### Upgrading React on Rails Pro

Treat React on Rails Pro as a coupled Ruby + JavaScript package upgrade.

When changing `react_on_rails_pro` in `Gemfile`, also update the matching npm packages:

- `react-on-rails-pro`
- `react-on-rails-pro-node-renderer`
- `react-on-rails-rsc` when the release notes require it

Use Ruby prerelease versions like `16.7.0.rc.0`, but npm prerelease versions like `16.7.0-rc.0`.

Regenerate and commit both Ruby and JavaScript lockfiles:

- `Gemfile.lock`
- `yarn.lock`, `package-lock.json`, or `pnpm-lock.yaml`

Suggested verification:

```bash
bundle install
yarn install --non-interactive
yarn install --frozen-lockfile --non-interactive --prefer-offline
bundle exec rails react_on_rails:generate_packs
NODE_ENV=development bundle exec bin/shakapacker

For RSC apps, also verify that the asset build emits both:

• react-client-manifest.json
• react-server-client-manifest.json

Then run the app's RSC/server-rendering specs.

## Possible landing spots

Potential places for this guidance:

- main `README.md` "Upgrading React on Rails" section
- docs site upgrade page
- React on Rails Pro / RSC setup docs
- generated app docs or template comments if there is a standard place for upgrade notes

## Acceptance criteria

- Upgrade docs mention the Ruby gem and npm package coupling.
- Docs mention committing both Ruby and JS lockfiles.
- Docs mention Ruby vs npm prerelease version formatting.
- RSC apps get a manifest verification note for `react-client-manifest.json` and `react-server-client-manifest.json`.
- The guidance is concrete enough for coding agents to follow without inferring hidden coupling.