@samitouri / QOS-React / commits / fbfecd13ce

Write a release guide (#8705)

* Write a release guide * Style nit

Dan Abramov committed Jan 9, 2017 at 06:39 UTC fbfecd13ce03d0386ea93b73cc645ccc09bbbed3
1 file changed +404 -22
scripts/release-manager/Readme.md
+404 -22
@@ -2,42 +2,424 @@
2
3 This is a tool that is being used to manage React releases.
4
5 -General prereqs:
6 -- A separate clone of React. This clone can be anywhere, so long as it is a separate working copy. Ideally this is where you are most comfortable working on React.
7 -- Your `react` clone should have the latest commits fetched before running commands. You may need to rebase or reset & re-run commands if not.
5 +## Prerequisites
6
7 +You should have an existing clone of the React repo. We will call this a **“working copy”**. Ideally this is where you are most comfortable working on React.
8
10 -## Commands
9 +Your working copy of React **should be up to date**. Check out the `master` branch in it and run `git pull` just to be sure.
10
12 -### `init`
11 +## Cloning the Release Manager
12
14 -Run this first, it will make sure you have a GitHub token generated, letting you use the API.
13 +**If this is your first time using the Release Manager**, you need to set it up.
14 +Skip this section if you’ve done this before.
15
16 -### `docs-prs`
16 +The Release Manager is also located inside the React repository so you need to **clone it to a separate folder**. Call it something other than `react` so that you don’t confuse it with the working copy.
17
18 -Cherry-picks PRs that have the `Documentation: needs merge to stable` label from `master` to the current branch. Then it removes the label from the PRs and pushes the branch to the remote it's tracking (resulting in Travis CI rebuilding the website)
18 +Check it out, install the dependencies, and run the CLI:
19
20 -**Prereqs:**
21 -- Have your `react` clone on the branch from which the production website is generate (currently `15-stable`)
20 + ```
21 + cd ~/projects # or wherever
22 + git clone https://github.com/facebook/react.git react-release-manager
23 + cd react-release-manager/scripts/release-manager
24 + yarn
25 + ./cli.js
26 + ```
27 +
28 + You will see a command-line interface that lets you enter commands.
29 + It will need to learn a few things to work on your machine.
30 + Type `init` and press Enter. It will ask you a few prompts:
31 +
32 + 1. `GitHub token? (needs "repo" privs)`
33 + Follow [these instructions](https://help.github.com/articles/creating-an-access-token-for-command-line-use/) to generate a GitHub token. Make sure to put a checkmark for `repo` privileges. Don’t share it with anyone!
34
23 -### `stable-prs`
35 + 2. `Location of local React checkout?`
36 + Enter the local path to your React working copy. For example, it is `~/projects/react` on my machine.
37 +
38 +Now you should be all set for releasing React on this machine!
39
25 -Cherry-picks PRs that are set to the `15-next` milestone. Handles merge conflicts by pausing & allowing you to switch to your working copy of React to manually merge. A menu allows you to continue from where you left off.
40 +## Before You Do Anything Else
41
27 -**Prereqs:**
28 -- Have your `react` clone on the dev branch (currently `15-dev`)
42 +You should have two separate React checkouts by now:
43
30 -### `version`
44 +* **The Release Manager copy.** The previous section described how to set it up. You will only use this checkout for *running* the Release Manager. Run `git checkout master` and `git pull` to ensure it is up-to-date.
45
32 -Bumps the version in all the places that need it.
46 +* **Your working copy of React.** The Release Manager will operate on it, and you will fix any merge conflicts inside of it. This should be the folder path you specified when you ran `init` in the previous section. Run `git checkout master` and `git pull` to ensure it is up-to-date.
47
34 -### `npm-publish`
48 +Both clones clean and up-to-date?
49 +If you aren’t already running it, run the Release Manager CLI:
50
36 -Publishes all built packages to npm (`next` dist-tag) and then for stable releases, also updates the `latest` dist-tag.
51 +```
52 +cd react-release-manager/scripts/release-manager
53 +./cli.js
54 +```
55
38 -**Prereqs:**
39 -- Have done everything else required for releasing (updating version, etc) and run `grunt build` or `grunt release`.
56 +Keep your working copy and the running Release Manager in separate terminal tabs.
57
41 -### `q`
58 +## Updating the Documentation
59 +
60 +When we merge a pull request to the documentation and it is relevant to the current version, we tag it with a `Documentation: needs merge to stable` label. The Release Manager can cherry-pick those commits so that they appear on the website.
61 +
62 +The documentation is built from the current stable branch. For example, for React 15.x the branch is called `15-stable`. Switch your working copy to it:
63 +
64 +```
65 +cd react
66 +git checkout 15-stable
67 +git pull
68 +```
69 +
70 +Then, in the Release Manager, run the command:
71 +
72 +```
73 +docs-prs
74 +```
75 +
76 +The Release Manager should find the PRs that haven’t been merged yet. Reply with `y` to get them merged and then with `y` to push your changes.
77 +
78 +**Tip:** If you see an error like `The previous cherry-pick is now empty, possibly due to conflict resolution` it might mean that there’s a stray PR with a label that has already been merged to the stable branch. In this case you need to remove the label manually and retry the command.
79 +
80 +## Cutting a Release
81 +
82 +### Verifying Permissions
83 +
84 +In the Release Manager, verify you have npm publish permissions:
85 +
86 +```
87 +npm-check-access
88 +```
89 +
90 +You will need to get all permissions before you can proceed.
91 +
92 +### Cherry Picking PRs
93 +
94 +If the permissions are cool, run:
95 +
96 +```
97 +start-release
98 +```
99 +
100 +**Tip:** if you get an error saying `'upstream' does not appear to be a git repository`, run `git remote add upstream https://github.com/facebook/react.git` in your working copy of React and try again.
101 +
102 +If everything went well, you should see a green `OK!` in the output.
103 +
104 +Create a new milestone in the [GitHub web interface](https://github.com/facebook/react/milestones) for the new release. Name it exactly after the version you intend to cut (e.g. `15.4.1`). Then run:
105 +
106 +```
107 +stable-prs
108 +```
109 +
110 +First, choose the current major “stable” milestone (such as `15-next`). Note that the Release Manager only sees merged PRs that have this milestone.
111 +
112 +**Tip:** our 15.x branch has diverged significantly so we are using `15-hipri` for things we really need to get out, and `15-lopri` for everything else. This is a temporary situation that should get better after Fiber is out.
113 +
114 +Next, choose the milestone you just created. This one should be specific and correspond to the version you intend to publish (such as `15.4.1`). The Release Manager will re-tag all PRs matching the previous “stable” milestone with this specific milestone after cherry-picking them.
115 +
116 +Finally, pick all appropriate labels with a spacebar. For example, a patch release usually contains `exempt` and `patch` PRs, and a minor release contains `minor` PRs in addition to them.
117 +
118 +Now the Release Manager will find all relevant PRs and attempt to cherry-pick them. Before agreeing to this, copy the list of PRs it prints out so that you can look them up later when you write the changelog.
119 +
120 +It is likely that some PRs won’t get merged cleanly. You’ll need to manually resolve the conflicts in the working copy. If the resolutions are not obvious it might be a sign the branches diverged too much which might be bad. (Talk to the team.)
121 +
122 +### Verifying the Changes
123 +
124 +Your working copy should now be in a clean state on a development branch. For example, during 15.x the development branch is `15-dev`.
125 +
126 +Verify it by running:
127 +
128 +```
129 +git status
130 +
131 +>On branch 15-dev
132 +>Your branch is ahead of 'origin/15-dev' by 10 commits.
133 +> (use "git push" to publish your local commits)
134 +>nothing to commit, working directory clean
135 +```
136 +
137 +Next, run `npm test`.
138 +
139 +If there are any issues you might have introduced mistakes resolving conflicts.
140 +You can fix them in a separate commit.
141 +
142 +**Tip:** tests might also be failing if dependency versions are incorrect. You might want to run `yarn` first since sometimes `package.json` on master is different from the stable branches.
143 +
144 +### Push and Choose the Branch
145 +
146 +If you followed the guide correctly (and ran `start-release` in the beginning), you should be on a “stable development” branch such as `15-dev`. Now is a good time to push the development branch:
147 +
148 +```
149 +git push
150 +```
151 +
152 +Then comes the important part.
153 +**If you plan to cut a stable release, switch the branch to the stable branch now.**
154 +
155 +For example, if you plan to cut `15.4.1` (rather than a `15.4.1-0` alpha release), run:
156 +
157 +```
158 +git checkout 15-stable
159 +git merge --no-ff 15-dev
160 +```
161 +
162 +This will merge the commits you cherry-picked into the stable branch.
163 +
164 +However, if you plan to cut an alpha or a beta, you should stay on the “stable development” branch.
165 +
166 +### Update the Shrinkwrap
167 +
168 +Run this so that the build is reproducible:
169 +
170 +```
171 +rm npm-shrinkwrap.json
172 +rm -rf node_modules
173 +npm cache clear
174 +npm i
175 +npm shrinkwrap --dev
176 +```
177 +
178 +Check `git diff`. Do changes look sensible?
179 +
180 +**Tip:** there are buggy npm versions that remove information from shrinkwrap. If you see a lot of `"dev": true` lines removed, you may be on a buggy version. Last time I tried, `npm@3.10.8` worked well.
181 +
182 +Commit your changes:
183 +
184 +```
185 +git commit -am 'Update shrinkwrap'
186 +```
187 +
188 +If you’re feeling extra careful, you can run `npm test` again.
189 +
190 +### Write the Changelog
191 +
192 +**This step is only necessary for a stable release.**
193 +If you’re just cutting an alpha, you should skip it.
194 +
195 +Open `CHANGELOG.md` in the working copy and add release notes in the same format as earlier. It’s usually a good idea to summarize changes in a friendly way instead of using PR titles. While you may skip non-essential changes, it’s still good to give credit to contributors, so maybe group them together. You can verify that you haven’t messed up the markup by previewing them in an online Markdown editor.
196 +
197 +Commit your changes, for example:
198 +
199 +```
200 +git commit -am 'Add <put the version here> changelog'
201 +```
202 +
203 +You will see the commit hash. Copy it in your editor. You will need it later to cherry-pick the changelog update to master.
204 +
205 +### Bump the Version
206 +
207 +In the Release Manager, run:
208 +
209 +```
210 +version
211 +```
212 +
213 +It will ask you about the version you want to ship and it will commit the result with a tag.
214 +
215 +We’re not pushing anything yet, it will just create a local commit.
216 +
217 +### Ensure You Have the Bower Repo
218 +
219 +**This step is only necessary for a stable release.**
220 +If you’re just cutting an alpha, you should skip it.
221 +
222 +There’s another repository you need to clone!
223 +This time, it should be a sibling of your React working copy.
224 +
225 +In the working copy directory, you can run:
226 +
227 +```
228 +git clone https://github.com/reactjs/react-bower.git ../react-bower
229 +```
230 +
231 +### Build It!
232 +
233 +The next step depends on the type of release you want to cut.
234 +
235 +For a **stable** release, run in the working copy:
236 +
237 +```
238 +./node_modules/.bin/grunt release
239 +```
240 +
241 +This will create the build products in the working copy. You won’t see changes in git because the `build` folder is ignored. It will also create a commit and a tag in the `../react-bower` folder. I recommend checking `git log` and running `git show <put last commit hash here>` to verify the changes roughly correspond to what you expect.
242 +
243 +For a **pre-release**, run this instead:
244 +
245 +```
246 +npm run build
247 +```
248 +
249 +### Verify the Build Works
250 +
251 +At the very least, open `fixtures/globals.html` in the browser. You should see a “Hello, World!” fading in, and the console should have no errors.
252 +
253 +If you changed anything related to how packages are created, I recommend following the instructions in `fixtures/README.md` and verifying that each of those manual tests works. You can skip the “build React” step in it but still need to build the fixtures.
254 +
255 +They are manual tests, so the CI wouldn’t have caught errors in them.
256 +
257 +### Update the Docs
258 +
259 +**This step is only necessary for a stable release.**
260 +If you’re just cutting an alpha, you should skip it.
261 +
262 +You will see that `docs/js/react-dom.js` and `docs/js/react.js` have changed. This is because the docs are now using a newer version of React. In addition to those changes, bump the version inside `docs/_config.yml`:
263 +
264 +```diff
265 +- react_version: 15.4.0
266 ++ react_version: <put the new version here>
267 +```
268 +
269 +Now commit the changes:
270 +
271 +```
272 +git commit -am 'Update React version in docs'
273 +```
274 +
275 +### Push the Working Copy
276 +
277 +Now we are ready to push the branch in the working copy:
278 +
279 +```
280 +git push
281 +git push --tags
282 +```
283 +
284 +### Release on Bower
285 +
286 +**This step is only necessary for a stable release.**
287 +If you’re just cutting an alpha, you should skip it.
288 +
289 +Go to the Bower folder from your working copy and push the new commit and tag:
290 +
291 +```
292 +cd ../react-bower
293 +git push
294 +git push --tags
295 +cd ../react
296 +```
297 +
298 +### Release on npm
299 +
300 +In the Release Manager, run:
301 +
302 +```
303 +npm-publish
304 +```
305 +
306 +### Cherry-Pick the Changelog
307 +
308 +**This step is only necessary for a stable release.**
309 +If you’re just cutting an alpha, you should skip it.
310 +
311 +Remember how you saved the hash of the commit changelog a few hours before?
312 +
313 +Now it’s time to switch our working copy to `master` and cherry-pick it:
314 +
315 +```
316 +git checkout master
317 +git pull
318 +git cherry-pick <hash of the changelog commit>
319 +```
320 +
321 +Verify you picked the right commit:
322 +
323 +```
324 +git diff HEAD~
325 +```
326 +
327 +Looks good? Push it.
328 +
329 +```
330 +git push
331 +```
332 +
333 +### Creating a GitHub Release
334 +
335 +**This step is only necessary for a stable release.**
336 +If you’re just cutting an alpha, you should skip it.
337 +
338 +Copy your new release notes from `CHANGELOG.md` and [create a new Release](https://github.com/facebook/react/releases/new) on GitHub. Choose the tag version you just pushed in the dropdown so that it says “Existing tag”. Paste the release notes and push the button.
339 +
340 +### Force-Updating the Website
341 +
342 +**This step is only necessary for a stable release.**
343 +If you’re just cutting an alpha, you should skip it.
344 +
345 +Normally the docs should update themselves after CI runs.
346 +However sometimes our CI might be slow or something might break.
347 +
348 +You can rebuild the docs manually if you want to.
349 +Make sure you have a React copy in a sibling folder called `react-gh-pages`:
350 +
351 +```
352 +git clone https://github.com/facebook/react.git ../react-gh-pages
353 +```
354 +
355 +Then make sure it’s on `gh-pages` branch and that it’s up-to-date:
356 +
357 +```
358 +cd ../react-gh-pages
359 +git checkout gh-pages
360 +git pull
361 +```
362 +
363 +Switch back to the working copy and go to the `docs` folder:
364 +
365 +```
366 +cd ../react/docs
367 +```
368 +
369 +Switch to the stable branch (the one you just spent a lot of time with).
370 +For example:
371 +
372 +```
373 +git checkout 15-stable
374 +```
375 +
376 +Build the docs now:
377 +
378 +```
379 +bundle install # Might need sudo.
380 +bundle exec rake release
381 +```
382 +
383 +If this fails, maybe you’re missing some Ruby dependencies:
384 +
385 +```
386 +gem install bundler
387 +```
388 +
389 +Install them and try again.
390 +
391 +This should not produce any changes in the working copy, but `react-gh-pages` should get some file changes:
392 +
393 +```
394 +cd ../../react-gh-pages
395 +git diff
396 +```
397 +
398 +If they look alright, commit and push them:
399 +
400 +```
401 +git commit -am 'Rebuild the website'
402 +git push
403 +```
404 +
405 +Now open https://facebook.github.io/react/, give it a few minutes, refresh, and behold.
406 +
407 +Don’t forget to switch to `master` for the future development.
408 +
409 +```
410 +git checkout master
411 +```
412 +
413 +### Bonus: Trying It Out
414 +
415 +Run:
416 +
417 +```
418 +npm i -g create-react-app
419 +create-react-app ../my-new-app
420 +cd ../my-new-app
421 +npm start
422 +```
423 +
424 +This should use the latest version of React.
425
43 -A secret alias to `exit` because `q` is faster.