Improve pactch release process docs (#14923)
Brian Vaughn committed
Feb 22, 2019 at 07:43 UTC
f708f9e307e5d2579a019b7d53cb06bac63d6d44
2 files changed
+59
-2
scripts/release/README.md
+31
-1
@@ -5,7 +5,7 @@ The release process consists of several phases, each one represented by one of t
5
A typical release goes like this:
6
1. When a commit is pushed to the React repo, [Circle CI](https://circleci.com/gh/facebook/react/) will build all release bundles and run unit tests against both the source code and the built bundles.
7
2. Next the release is [**published as a canary**](#publishing-a-canary) using the [`prepare-canary`](#prepare-canary) and [`publish`](#publish) scripts. (Currently this process is manual but might be automated in the future using [GitHub "actions"](https://github.com/features/actions).)
8
-3. Finally, a canary releases can be [**promoted to stable**](#publishing-a-stable-release) using the [`prepare-stable`](#prepare-stable) and [`publish`](#publish) scripts. (This process is always manual.)
8
+3. Finally, a canary releases can be [**promoted to stable**](#publishing-a-stable-release)<sup>1</sup> using the [`prepare-stable`](#prepare-stable) and [`publish`](#publish) scripts. (This process is always manual.)
9
10
The high level process of creating releases is [documented below](#process). Individual scripts are documented as well:
11
* [`create-canary`](#create-canary)
@@ -13,6 +13,8 @@ The high level process of creating releases is [documented below](#process). Ind
13
* [`prepare-stable`](#prepare-stable)
14
* [`publish`](#publish)
15
16
+<sup>Note that [**creating a patch release**](creating-a-patch-release) has a slightly different process than a major/minor release.</sup>
17
+
18
# Process
19
20
## Publishing a Canary
@@ -53,8 +55,36 @@ Once this step is complete, you're ready to publish the release:
55
scripts/release/publish.js --tags next latest
56
```
57
58
+After successfully publishing the release, follow the on-screen instructions to ensure that all of the appropriate post-release steps are executed.
59
+
60
<sup>1: You can omit the `version` param if you just want to promote the latest canary to stable.</sup>
61
62
+## Creating a Patch Release
63
+
64
+Patch releases should always be created by branching from a previous release. This reduces the likelihood of unstable changes being accidentally included in the release.
65
+
66
+Begin by creating a branch from the previous git tag<sup>1</sup>:
67
+
68
+```sh
69
+git checkout -b 16.8.3 v16.8.2
70
+```
71
+
72
+Next cherry pick any changes from master that you want to include in the release:
73
+
74
+```sh
75
+it cherry-pick <commit-hash>
76
+```
77
+
78
+Once you have cherry picked all of the commits you want to include in the release, push your feature branch and create a Pull Request (so that Circle CI will create a canary):
79
+
80
+```sh
81
+git push origin 16.8.3
82
+```
83
+
84
+Once CI is complete, follow the regular [**canary**](#publishing-a-canary) and [**promote to stable**](#publishing-a-stable-release) processes.
85
+
86
+<sup>1: The `build-info.json` artifact can also be used to identify the appropriate commit (e.g. [unpkg.com/react@16.8.3/build-info.json](https://unpkg.com/react@16.8.3/build-info.json) shows us that react version 16.8.3 was created from commit [`29b7b775f`](https://github.com/facebook/react/commit/29b7b775f)).</sup>
87
+
88
# Scripts
89
90
## `create-canary`
scripts/release/publish-commands/print-follow-up-instructions.js
+28
-1
@@ -7,6 +7,7 @@ const {existsSync} = require('fs');
7
const {readJsonSync} = require('fs-extra');
8
const {join} = require('path');
9
const theme = require('../theme');
10
+const {execRead} = require('../utils');
11
12
const run = async ({cwd, packages, tags}) => {
13
// All packages are built from a single source revision,
@@ -20,6 +21,10 @@ const run = async ({cwd, packages, tags}) => {
21
`${cwd}/build/node_modules/react/package.json`
22
);
23
24
+ const branch = await execRead('git branch | grep \\* | cut -d " " -f2', {
25
+ cwd,
26
+ });
27
+
28
clear();
29
30
if (tags.length === 1 && tags[0] === 'canary') {
@@ -64,9 +69,19 @@ const run = async ({cwd, packages, tags}) => {
69
70
console.log();
71
console.log(
67
- theme`{header Don't forget to update and commit the }{path CHANGELOG}`
72
+ theme`{header Don't forget to also update and commit the }{path CHANGELOG}`
73
);
74
75
+ if (branch !== 'master') {
76
+ console.log();
77
+ console.log(
78
+ theme`{header Don't forget to cherry-pick any updated error codes into the} {path master} {header branch}.`
79
+ );
80
+ console.log(
81
+ theme`Else they will not be properly decoded on {link reactjs.org}.`
82
+ );
83
+ }
84
+
85
// Prompt the release engineer to tag the commit and update the CHANGELOG.
86
// (The script could automatically do this, but this seems safer.)
87
console.log();
@@ -104,6 +119,18 @@ const run = async ({cwd, packages, tags}) => {
119
);
120
}
121
}
122
+
123
+ // Updating reactjs.org accomplishes two things:
124
+ // (1) It ensures our Gatsby error codes plugin runs with the latest error codes.
125
+ // (2) It keeps the React version shown in the header up to date.
126
+ console.log();
127
+ console.log(
128
+ theme.header`Once you've pushed changes, update the docs site.`
129
+ );
130
+ console.log(
131
+ 'This will ensure that any newly-added error codes can be decoded.'
132
+ );
133
+
134
console.log();
135
}
136
};