React: New Release Checklist

[gaearon]

The current release process is convoluted. I think we agreed that we won’t be maintaining stable branches from now on, and will release from master. This means breaking changes land behind a flag. In this issue I am documenting the new master-based release process. It is intended to be exhaustive so let me know if something is missing.

If we agree on this, I’ll be deleting the existing documentation and point it to this issue instead. This issue is in checklist format to be copy-pasteable for specific release issues (h/t @flarnie for the tip). Ideally we should automate some parts of this, potentially by fixing RRM to work with this model.

So You Want to Cut a Release...

Ensure all commits in master were tested at Facebook.

• Check that they were a part of the latest internal sync.
• For stable releases, prefer that they’ve been landed for a week or so.
• Only skip this step if you really know what you’re doing!

Verify that you have npm permissions.

• [ ] You’re in npm owner ls react
• [ ] You’re in npm owner ls react-art
• [ ] You’re in npm owner ls react-dom
• [ ] You’re in npm owner ls react-test-renderer
• If not, ping someone on the team!

Ensure your React is fresh.

• [ ] Ensure you’re on master
• [ ] Do a git pull
• [ ] Is master green on CI? Check the most recent commits.
• [ ] Check that your local git log output matches the commit list.
• [ ] Run yarn in the repo root.

Ensure runtime dependencies match what users would get.

• [ ] For fbjs:
  
  
  
  • [ ] Look at the version range of fbjs in root package.json.
  
  
  • [ ] Ensure all packages/*/package.json depending on fbjs specify the same range.
  
  
• [ ] For object-assign:
  
  
  
  • [ ] Look at the version range of object-assign in root package.json.
  
  
  • [ ] Ensure all packages/*/package.json depending on object-assign specify the same range.
  
  
• [ ] For prop-types:
  
  
  
  • [ ] Look at the version range of prop-types in root package.json.
  
  
  • [ ] Ensure all packages/*/package.json depending on prop-types specify the same range.
  
  
• [ ] Run yarn upgrade object-assign prop-types fbjs
• [ ] This might change the lockfile. This should not change any package.json.
• [ ] Commit the changes, if any.

Do the local sanity checks in the repo root.

• [ ] Run yarn test in the repo root.
• [ ] Run yarn lint in the repo root.
• [ ] Run yarn flow in the repo root.

_STABLE RELEASE ONLY:_ Update error codes.

• [ ] Run yarn build -- --extract-errors in the repo root.
• [ ] If scripts/error-codes/codes.json changes, git commit -am 'Update error codes'
• [ ] Maybe: If we still have a separate *-stable branch for docs when you’re reading this, we need to cherry-pick that commit to that branch. This makes sure the website decoder knows about the updated error codes. But ideally we should just change docs to serve from master.

_STABLE RELEASE ONLY:_ Write the changelog.

• [ ] Open CHANGELOG.md and add release notes in the same format as earlier.
• [ ] Make sure the changes are easy to understand. Friendly one-liners are better than PR titles.
• [ ] Make sure all contributors are credited, just like before.
• [ ] Verify that the markup isn’t messed up by previewing it in the online editor.

Update the version.

• [ ] Update version in root package.json
• [ ] Update export in src/ReactVersion.js
• [ ] Update both version and React version in peerDependencies in all packages/*/package.json:
  
  
  
  • [ ] packages/react/package.json
  
  
  • [ ] packages/react-art/package.json
  
  
  • [ ] packages/react-dom/package.json
  
  
  • [ ] packages/react-noop-renderer/package.json
  
  
  • [ ] packages/react-test-renderer/package.json
  
  
  • [ ] If you see any other packages, update this list :-)
  
  
• [ ] Run yarn version-check to verify your changes.
• [ ] git commit -am "<version number>"

Build it!

• [ ] Run yarn build in the repo root.

Run fast packaging smoke test.

• [ ] Open fixtures/packaging/babel-standalone/dev.html in the browser for a smoke test.
• [ ] It should say “Hello world!”

Run slow packaging smoke test.

• [ ] Go to cd fixtures/packaging and run node build-all.js
• [ ] npm install -g serve
• [ ] Go to the repo root and run serve -s .
• [ ] Open http://localhost:5000/fixtures/packaging/ and verify every iframe shows “Hello World!”

Release!

• [ ] Run git push
• [ ] Run git push --tags
• [ ] Go to build/packages
  
  
  
  • [ ] For every subfolder:
  
  
  • [ ] For non-stable versions: Run npm publish --tag next in the subfolder.
  
  
  • [ ] For stable versions: Run npm publish in the subfolder.
  
  
• [ ] Run npm info <package> dist-tags to verify that things were published as you expect.
• [ ] FIXME: We should really automate this part because it’s currently not atomic.

_STABLE RELEASE ONLY:_ Create GitHub Release.

• [ ] Open New Release page on GitHub.
• [ ] Choose the tag version you just pushed in the dropdown so that it says “Existing tag”.
• [ ] Paste the new release notes from CHANGELOG.md.
• [ ] Attach all files in build/dist/*.js except react-art.* to the release.
• [ ] Press “Publish release”!

_STABLE RELEASE ONLY:_ Update the version reported on the website.

• [ ] Open docs/_config.yml
• [ ] Change react_version in it to the newly published version.
• [ ] git commit -am "Update the reported React version on the website"
• [ ] Maybe: If we still have a separate *-stable branch for docs when you’re reading this, we need to cherry-pick that commit to that branch. This makes sure the website knows about the updated config. But ideally we should just change docs to serve from master.

_STABLE RELEASE ONLY:_ Update Bower.

• [ ] Clone the Bower repo outside of main repo: git clone https://github.com/reactjs/react-bower.git
• [ ] Make sure it’s on master and you did git pull
• [ ] Delete all JS files from the Bower repo and copy all build/dist/*.js from React repo into it.
• [ ] In the Bower repo, git commit -am "<version number>"
• [ ] In the Bower repo, git tag -a v<version number> (Don’t miss the v!)
• [ ] In the Bower repo, git push and git push --tags

_STABLE RELEASE ONLY:_ Try it out!

• [ ] npm i -g create-react-app
• [ ] create-react-app myapp
• [ ] cd myapp
• [ ] npm start

_STABLE RELEASE ONLY_: Reach out to DOM team.

• [ ] Reach out to the DOM team (@nhunzaker @jquense @aweary) in case they would like to go through DOM fixtures. (This doesn’t block the release.)

[aweary]

Should we add a note for running through the browser fixtures as well? Just in case we failed to review the browser fixtures before merging a DOM change.

[gaearon]

I thought about it, but this is already a ton of work by this point. How much more work would going through DOM fixtures be? If we automate publishing them then maybe we can have QA people help go through them. @sophiebits had ideas about it.

[flarnie]

@aweary Dan and I discussed that a bit - we expect that when changes land to DOM related things, we'll run through the DOM fixtures, and when we make packaging changes we test the packaging fixtures then. We agreed that doing a "smoke test" of the packaging fixtures is probably good for a release, rather than re-doing all of the fixture testing by hand.

We also do a step where we sync React into Facebook, and do pretty extensive manual testing of our internal uses of React, so anything that went into a sync should be very well tested.
Can we add that to this checklist? Even if it's just a note - we could point to internal docs on that process, or just comment about what to search for in the internal dex/wiki.

[gaearon]

@flarnie 👍 added

[aweary]

I thought about it, but this is already a ton of work by this point. How much more work would going through DOM fixtures be?

It would take a good chunk of time, but maybe we can just add it as non-blocking and defer it to someone else who has the time who can give it a 👍 for the release? I'm sure myself, @nhunzaker or @jquense would be happy to contribute on that front.

I just worry since there's currently nothing in place that enforces that DOM fixtures be checked when DOM changes are merged, so if we mess up and forget we could slip a regression into a stable release.

If we automate publishing them then maybe we can have QA people help go through them.

That would be great, I wonder if we could use something like danger to watch for changes to DOM-related files and add a note reminding us to check the published fixtures before merge? We can talk about that another time though 😄

[gaearon]

I added a last note about reaching out to you folks :-)

[flarnie]

This is the best - thanks for creating it. 🥇💎🎶
I'm excited that we have one source of truth for this, in a visible place, and we'll work towards automating it.

Some thoughts:

• What to tag it so that it's clear this is not just another bug report? big picture and/or release?
• Do we want to include a step for updating yarn.lock? Seems like this may now be covered by "Ensure runtime dependencies match what users would get."
• Do we want to update results.json? I know ideally we are updating that regularly but since in practice we don't, it could be good to flag any size regressions before cutting a release.

I love all the details. Looks good to me.

Going to make a clone of it for specifically the 16 RC, and probably will continue through the process after lunch. The part I've done so far is open PRs for the "Update error codes." steps.

[gaearon]

Do we want to include a step for updating yarn.lock? Seems like this may now be covered by "Ensure runtime dependencies match what users would get."

Yes, that's the only thing we need to do during the release. The rest (updating dev dependencies) should be done during normal development cycle once in a while—when we feel like updating them :-) And we should land a sync after doing that.

Do we want to update results.json? I know ideally we are updating that regularly but since in practice we don't, it could be good to flag any size regressions before cutting a release.

Sure. Although by the time we do a sync it's usually late to fix size :-) But we should add something.

[flarnie]

I think we want yarn upgrade object-assign@^THAT_VERSION instead of yarn add --dev 'prop-types@^THAT_VERSION', because yarn add won't change the lockfile vs. yarn upgrade will bump it to the latest version which is still compatible with the package.json.

[flarnie]

Updating based on my previous comment now, after chatting with @gaearon it sounds like this is what we want.

[gaearon]

From the Yarn docs it sounds like just yarn upgrade object-assign prop-types fbjs will work and do the right thing.

[flarnie]

Just a note - let's add something about verifying using npm info <package> dist-tags

[bvaughn]

Ideally we should automate some parts of this, potentially by fixing RRM to work with this model.

I will be happy to do this.