react-native-community · alloy · Mar 10, 2020 · Mar 2, 2020 · Mar 2, 2020 · Mar 2, 2020
diff --git a/README.md b/README.md
@@ -4,42 +4,100 @@
 
 Stay up-to-date with the release activities of [React Native](https://github.com/facebook/react-native/) by [watching](https://github.com/react-native-community/releases/subscription) for [status reports](https://github.com/react-native-community/releases/issues?q=is%3Aopen+is%3Aissue+label%3A%22release+status%22). Or you can follow along as the release notes are prepared and help reviewing the overall [changelog](https://github.com/react-native-community/releases/blob/master/CHANGELOG.md).
 
-## Release Status Issues
-
-Progress towards release is tracked in issues, based on labels:
-
-- _release status_: here you can read the status for the future/RC level releases
-- _stable_: here you can read the status for the current stable release
-- _backport requests_: here you can request cherry-picks for the current stable release, that will be included in the next patch version
-
-Note that these issues are made to keep the conversation focused strictly on the status of each one - please refrain from going off-topic.
-
-## Changelog
-
-The changelog in this repository is a community-driven effort to provide a helpful and informative summary of React Native's rapidly changing codebase along with a full list of commits.
-
-The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/), and generated via the script described in the next section.
-
-In order to allow additional research, the commits that relate to a change are listed with their hashes. The revisions listed typically are the merge commits, so as to match the code that a user may find in their own copy. Authors are attributed to encourage recognizing the contributors for supporting React Native.
-
-### Changelog helper script
-
-In order to generate the Changelog, we use a script that, given a base version and a target version, checks all the commits between the two versions and parses release notes and authors in the commit message - and then prints it in the terminal for easy/copy paste.
-
-To use it first off `git clone` the repo, then `yarn` and finally you can use it like in the following example: `./changelog-generator.js -b v0.57.5 -c v0.57.6`.
-
-## "When will my fix make it into a release?"
-
-React Native follows a release cycle not strictly monthly - you can read more [about it here](https://github.com/react-native-community/discussions-and-proposals/issues/17). When creating a new release, we cut a new branch from `master` (e.g. `0.61-stable`), with all the merged commits up to this point. After this initial cut, new commits on `master` will only be included on this release if they get manually cherry picked. Otherwise, they will be included in the next stable version (when a new cut from `master` will happen). This means that once a pull request is merged to the [core `react-native` repo](https://github.com/facebook/react-native), it may take one or two months for the changes to make it into a stable React Native release.
-
-To determine whether a fix or feature is present in a given release, you will need the commit hash where the fix or feature was added to the `master` branch of the core `react-native` repo. If you know the PR, you can look for the comment from **@facebook-github-bot** that says 'closed this in <COMMIT_HASH>'.
-
-Once you have the commit hash, navigate to `https://github.com/facebook/react-native/commit/<COMMIT_HASH>`. Look closely at the commit message, underneath which you will find a list of tags associated with the commit. These tags will tell you which releases contains this commit. For example, commit [5e80d95e034259af8c41b50756a623756cc81a77](https://github.com/facebook/react-native/commit/5e80d95e034259af8c41b50756a623756cc81a77) has the following tags as of this writing: `v0.55.0-rc.0 v0.54.2 v0.54.1 v0.54.0 v0.54.0-rc.4 v0.54.0-rc.3 v0.54.0-rc.2 v0.54.0-rc.0 latest`. These tags tell us that the commit first made it into the 0.54 release candidate, eventually landing in the 0.54 stable release. It is also present, as you'd expect, in the 0.55 release candidate (and should make it to 0.55 stable, and so on).
-
-If the commit is only present in `master` (i.e. has no tags), then the commit has yet to be picked up by a release (or it may have been included in a follow up cherry pick for a patch version). You can expect it to be included in the next release candidate that is cut once the designed features have all landed.
-
-## Backporting/cherry-picking of changes to existing builds
-
-From time to time, [backporting](https://en.wikipedia.org/wiki/Backporting) a change to an existing release (including candidates) may be needed. Examples include security issues or critical regressions. If you believe a pull request on `react-native` is a candidate for backporting, please mention it in the version associated _backport request_ issue.
-
-Please note that, if the change hasn't landed on `react-native`'s master, it can't be cherry picked to a release tag yet.
+## React Native’s Release Process
+
+At Facebook React Native is not consumed via released versions, instead they always consume the latest version of the `master` branch. This means that they are able to iterate fast for _their_ needs; if something is broken the fix is a single commit away.
+
+External users are of course similarly able to consume the latest `master` version, however this is most likely a too fast moving target for most–aside from turn around to get a fix in being longer.
+
+To reconcile these two different use-cases, React Native’s release process is a different one from the one many users are familiar within the JavaScript ecosystem.
+
+### The process at a high-level
+
+1. A branch for a new version is created from `master`–hereafter referred to as “the stable branch”. [⇒](./docs/release-process.md#initialize-the-process-for-a-new-version)
+1. A [release candidate][rc] is released from the stable branch, allowing the community to try it out and provide feedback–hereafter referred to as “the RC”. [⇒](./docs/release-process.md#publish-the-release-candidate)
+1. Additional changes that have landed in the `master` branch since the stable branch was originally created and are deemed required for the version to be finalized are [cherry-picked][cherry-picking] onto the stable branch. These can be bug-fixes for previously released versions, including the RC, or changes otherwise deemed an improvement for the version to be finalized, such as [UX]/[DX] improvements. [⇒](./docs/release-process.md#iterate-on-the-release-candidate)
+1. Steps 2 through 3 are repeated until consensus is reached that the version is good enough to be released as a stable version.
+1. A stable version is released and communications are sent out to the community informing them of the availability of a new stable version and what changes it includes.
+1. Steps 3 through 5 are repeated on the stable branch for bug-fixes _only_ and will result in a [patch release]. I.e. no release-candidates are published for patch versions.
+1. The entire process is repeated from step 1 for the next [minor version], which will include all the changes that were made on the `master` branch previously but were not yet cherry-picked.
+
+```
+┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
+            master branch            │
+│
+   ┌──────────────────────────────┐  │
+│  │                              │
+   │     pretty good bug-fix      │  │
+│  │                              │
+   └──────────────────────────────┘  │  ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
+│                  │                                 0.42-stable             │
+                   ▼                 │  │
+│  ┌──────────────────────────────┐        ┌──────────────────────────────┐  │
+   │                              │  │  │  │                              │
+│  │   zomg, amazing feature A!   │───────▶│         0.42.0-rc.0          │  │
+   │                              │  │  │  │                              │
+│  └──────────────────────────────┘        └──────────────────────────────┘  │
+                   │                 │  │                  │
+│                  ▼                                       ▼                 │
+   ┌──────────────────────────────┐  │  │  ┌──────────────────────────────┐
+│  │                              │        │                              │  │
+   │    whoops, fix feature A     │──┼──┼─▶│    whoops, fix feature A     │
+│  │                              │        │                              │  │
+   └──────────────────────────────┘  │  │  └──────────────────────────────┘
+│                  │                                       │                 │
+                   │                 │  │                  ▼
+│                  │                       ┌──────────────────────────────┐  │
+                   │                 │  │  │                              │
+│                  ▼                       │         0.42.0-rc.1          │  │
+   ┌──────────────────────────────┐  │  │  │                              │
+│  │                              │        └──────────────────────────────┘  │
+   │  wow, sweet new feature B!   │  │  │                  │
+│  │                              │                        ▼                 │
+   └──────────────────────────────┘  │  │  ┌──────────────────────────────┐
+│                  │                       │                              │  │
+                   │                 │  │  │            0.42.0            │
+│                  │                       │                              │  │
+                   │                 │  │  └──────────────────────────────┘
+│                  │                                       │                 │
+                   ▼                 │  │                  ▼
+│  ┌──────────────────────────────┐        ┌──────────────────────────────┐  │
+   │                              │  │  │  │                              │
+│  │  yikes, fix feature A more   │───────▶│  yikes, fix feature A more   │  │
+   │                              │  │  │  │                              │
+│  └──────────────────────────────┘        └──────────────────────────────┘  │
+                   │                 │  │                  │
+│                  │                                       ▼                 │
+                   │                 │  │  ┌──────────────────────────────┐
+│                  │                       │                              │  │
+                   │                 │  │  │            0.42.1            │
+│                  │                       │                              │  │
+                   │                 │  │  └──────────────────────────────┘
+│                  │                                                         │
+                   │                 │  └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
+│                  │
+                   │                 │  ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
+│                  │                                 0.43-stable             │
+                   ▼                 │  │
+│  ┌──────────────────────────────┐        ┌──────────────────────────────┐  │
+   │                              │  │  │  │                              │
+│  │    make feature B better     │───────▶│         0.43.0-rc.0          │  │
+   │                              │  │  │  │                              │
+│  └──────────────────────────────┘        └──────────────────────────────┘  │
+                   │                 │  │                  │
+│                  ▼                                       ▼                 │
+   ┌──────────────────────────────┐  │  │  ┌──────────────────────────────┐
+│  │                              │        │                              │  │
+   │      [history repeats]       │  │  │  │      [history repeats]       │
+│  │                              │        │                              │  │
+   └──────────────────────────────┘  │  │  └──────────────────────────────┘
+│                                                                            │
+ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘  └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
+```
+
+[rc]: https://en.wikipedia.org/wiki/Software_release_life_cycle#Release_candidate
+[cherry-picking]: https://wiki.c2.com/?CherryPicking
+[ux]: https://www.nngroup.com/articles/definition-user-experience/
+[dx]: https://medium.com/@albertcavalcante/what-is-dx-developer-experience-401a0e44a9d9
+[patch release]: https://semver.org/spec/v2.0.0.html#spec-item-6
+[minor version]: https://semver.org/spec/v2.0.0.html#spec-item-7
diff --git a/docs/branch-strategy.monopic b/docs/branch-strategy.monopic
diff --git a/docs/generate-changelog.md b/docs/generate-changelog.md
@@ -0,0 +1,3 @@
+# Generate changelog
+
+Point people: [@alloy](https://github.com/alloy), [@turnrye](https://github.com/turnrye)
diff --git a/docs/publish-release.md b/docs/publish-release.md
@@ -0,0 +1,86 @@
+# Publish a release
+
+_Point people: [@alloy](https://github.com/alloy), [@grabbou](https://github.com/grabbou), [@kelset](https://github.com/kelset)_
+
+1. First cleanup your environment:
+
+   - Remove the `RNTester` and `RNTestProject` apps from both the iOS simulator and Android emulator.
+   - Then remove any build-artifacts:
+     ```bash
+     rm react-native-*.tgz
+     rm -rf node_modules
+     ./gradlew clean
+     ./gradlew cleanBuildCache
+     rm -rf /tmp/RNTestProject
+     pushd RNTester
+     rm -rf Pods
+     xcodebuild -workspace RNTesterPods.xcworkspace -scheme RNTester clean
+     popd
+     ```
+
+1. Ensure you have everything installed that’s required to cut a release:
+
+   - The Android toolchain, as per the “Android development environment” section of [the react-native setup guide](https://reactnative.dev/docs/getting-started).
+   - Download [Android NDK 21](https://developer.android.com/ndk/downloads) and place it at `~/Library/Android/android-ndk-r21`, then add the following environment setup:
+     ```bash
+     export ANDROID_NDK_HOME=$HOME/Library/Android/android-ndk-r21
+     ```
+   - Latest iOS
+   - Latest yarn
+   - Latest CocoaPods
+   - Install dependencies:
+     ```bash
+     yarn install
+     pushd RNTester
+     pod install --repo-update
+     popd
+     ```
+
+1. Run the script that will guide you through manually testing whether `RNTester` and new applications work on both iOS and Android:
+
+   ```bash
+   ./scripts/test-manual-e2e.sh
+   ```
+
+1. In case your local branch has changes that do not yet exist on the remote, push them now and make not of possible deterioration of CI status.
+
+1. Bump the version numbers, which should also push the change to the remote:
+
+   ```bash
+   ./scripts/bump-oss-version.js [VERSION]
+   ```
+
+1. Pushing the changed version numbers will eventually kickoff the `publish_npm_package` workflow on CI, keep an eye on it.
+
+   ⚠️ Currently publishing fails due to SSH not being setup to accept github.com automatically. To workaround this:
+
+   - Re-run the failed build with SSH enabled.
+   - Look for the `Enable SSH` step and expand it to reveal details on how to connect to the VM through SSH.
+   - Connect through SSH as per the given instructions.
+   - Wait for the CI workflow to reach the `node ./scripts/publish-npm.js` step, then kill the process from your SSH session:
+     ```bash
+     ps -ax | grep 'node ./scripts/publish-npm.js'
+     kill [PID]
+     ```
+   - Restart the publish script interactively and type “yes” when asked to accept the fingerprint of github.com:
+     ```bash
+     node ./scripts/publish-npm.js
+     ```
+   - Once finished, quit the SSH session:
+     ```bash
+     exit
+     ```
+
+1. Test that npmjs.com returns the correct results:
+
+   ```bash
+   npm view react-native
+   ```
+
+1. Once more test that creating a new application works as expected:
+
+   ```bash
+   npx react-native init TestRelease --version [VERSION]
+   ```
+
+1. Communicate the release as per the instructions in the release-process doc. [⇒](./release-process.md)