diff --git a/README.md b/README.md index 3dddf29b240cd0..fc2a0ef8c5de7d 100644 --- a/README.md +++ b/README.md @@ -61,10 +61,11 @@ The source for the React Native documentation and website is hosted on a separat [React Native for Windows + macOS](https://microsoft.github.io/react-native-windows/) has its own separate documentation site where Windows and macOS specific information, like API docs and blog updates live. We are still working on the documentation for macOS, contributions are welcome! -### Examples +If you're looking for sample code, just browse the [RNTester folder](https://github.com/microsoft/react-native-macos/tree/master/packages/rn-tester) for examples -- Using the CLI in the [Getting Started](https://microsoft.github.io/react-native-windows/docs/rnm-getting-started) guide will set you up with a sample React Native for macOS app that you can begin editing right away. -- If you're looking for sample code, just browse the [RNTester folder](https://github.com/microsoft/react-native-macos/tree/master/packages/rn-tester) for examples +### Git flow and syncing with upstream + +For more details on how this fork handles keeping up with upstream, and how the general git flow works, check out [this dedicated document](./docs/GitFlow.md). ## License diff --git a/docs/GitFlow.md b/docs/GitFlow.md new file mode 100644 index 00000000000000..e2baf67be1aee0 --- /dev/null +++ b/docs/GitFlow.md @@ -0,0 +1,88 @@ + +# Git flow and Syncing with Upstream + +We aim to keep this forked repository as up to date as possible against [Meta's repository](https://github.com/facebook/react-native). This document explains guidelines for pulling in the newest commits and how new changes should be introduced to the codebase. + +For visual reference, here's a graph that showcases the relationship of core and this fork, along with all the main flows: + +![React Native macos git flow](./graphs/RNmacosGITFLOW.png "React Native macos git flow") + +In broad strokes, there are 4 flows we focus on: + +* (A) syncing `react-native-macos` to a new version of `react-native` +* (B) syncing a `0.XX-stable` branch to its upstream counterpart +* (C) adding new changes and fixes in the fork +* (D) doing a local commit against a `0.XX-stable` branch + +Here are the details on how we want to behave on each of these - to make things easier, we'll be using version 0.68 as the example version: + +## (A) syncing `react-native-macos` to a new version of `react-native` + +Because of the inherit way `react-native` works as an OSS repo on GitHub, we **DO NOT** want to sync the `react-native-macos` fork against a specific tag release. +What we want to do instead is to sync `react-native-macos` main branch against `react-native` main branch up to the commit on which the `0.68-stable` branch was created. + +This will avoid a lot of messiness caused by all the extra work that goes on in a `0.68-stable` branch upstream before a release reaches `0.68.0` (local commits, cherry picks, etc. as showcased in the graph). + +### how do I find the hash of the commit against which `0.XX-stable` branch was created? + +The quick&dirty way is composed of two steps. + +First, git clone locally `react-native` upstream (in a separate folder), and within it run +``` +git log main..0.68-stable --oneline | tail -1 +``` +This will return the first actual commit of the repo, in this case: +``` +0fd6ade8624 [0.68.0-rc.0] Bump version numbers +``` + +We can now use this reference to check the commit *right before it* in the [0.68-branch upstream on GitHub](https://github.com/facebook/react-native/tree/0.68-stable): + +![git history for upstream 68](./graphs/git-history-example.png "git history for upstream 68") + +So what we want now is to use the commit hash `8aa87814f62e42741ebb01994796625473c1310f` as reference point for syncing the fork and upstream `main` branches. + +Now we can move to: + +### do the "actual" upstream sync + +1. Within the `react-native-macos` local clone, create a reference to a remote to Meta's repo *(if not already present)* + 1. `git remote add meta https://github.com/facebook/react-native.git` + 2. `git pull meta` +2. Create a branch to work in: `git checkout -b meta68merge` +3. Pull the new contents at the merge point we want, meaning the hash commit we found earlier `git fetch meta 8aa87814f62e42741ebb01994796625473c1310f` +4. Do the merge at the point we want `git merge 8aa87814f62e42741ebb01994796625473c1310f` + +It's likely that the `git merge` command will cause in the order of 100s of merge conflicts: that's expected! Push the initial merge up to github **with** the merge conflicts, and open a draft PR. This makes it easier for other people to see where the errors are and help fix their platforms quickly. + +Now, the work is to address all the conflicts and make sure to keep the custom macos code around, without breaking anything. Good luck - this is the hardest part of working on this repo. + +Once the work in the `meta68merge` branch is completed, the PR must be merged **WITHOUT SQUASHING IT** in order to avoid messing up with the git history and reduce the likeliness of merge conflicts. + +Once this sync PR has been merged, a stable branch can be created: `git branch 0.68-stable` and we can move to (B). + +## (B) syncing a `0.XX-stable` branch to its upstream counterpart + +Once we have created a `0.68-stable` branch in our fork, it's time to "fast forward" it against its upstream counterpart. This procedure is basically the same as described above (making a new branch against `0.68-stable` and all), with two minor differences: + +1. we will use the latest commit on the `0.68-stable` [branch upstream](https://github.com/facebook/react-native/commits/0.68-stable) as hash reference for the `git fetch meta` and `git merge` commands. +2. we can safely merge squash the PR with this sync back into `0.68-stable` + +Once this is all done, we can finally start looking into making releases. For it, refer [to the dedicated doc](./Releases.md). + +Note: This step might happen multiple times during the lifespan of the 0.XX release cycle, given that upstream will also produce a few patch releases per each minor. If we are very closely up-to-date with upstream, we might want to consider mimicking the cherry-picks that happen upstream instead of making a whole merge/PR process. But it will be a case-by-case scenario consideration. + +## (C) adding new changes and fixes in the fork + +Because this fork adds new feature (the entire `macos` platform support) and other custom fixes, the general rule of thumb to follow is the following: + +1. make all the new changes as PRs against `react-native-macos`'s `main` branch +2. once the fix has been merge-squashed into `main`, it can be safely cherry picked to the stable branch. If you have the auth to do so, you don't need to open a PR to do so but you can simply use the command `git cherry-pick ` + +*(sidenote, if the fix you want to introduce is about the Android side of this project, please refer to the `android-patches` [README](./../android-patches/README.md))* + +## (D) doing a local commit against a `0.XX-stable` branch + +In some (hopefully) **rare** scenarios, you might have to do an hotfix on the `0.XX-stable` branch directly - when this happens, consider doing a separate PR the same fix against `main` branch, if necessary. + +There's no automatic syncing between `main` and a `0.XX-stable` branch, and we strongly suggest not doing merges between stable<->main to avoid the problems with the git history and merge conflicts mentioned previously. diff --git a/docs/KeepingRecent.md b/docs/KeepingRecent.md deleted file mode 100644 index 54b14e2e0253cd..00000000000000 --- a/docs/KeepingRecent.md +++ /dev/null @@ -1,40 +0,0 @@ - -# Keeping Recent on Facebook's Changes - -We aim to keep this forked repository as up to date as possible with [Facebook's repository](https://github.com/facebook/react-native). This document explains guidelines and responsibilities for pulling in the newest changes with the eventual goal of pushing all our changes back to Facebook and the React-Native-Community repos and deforking. - -## Merging a New Version of React Native -1. Create a reference to a remote to Facebook's repo - 1. In terminal: `git remote add facebook https://github.com/facebook/react-native.git` - 2. In terminal: `cd react-native/; git pull facebook` -2. Create a branch to work in. Below is for merging in Facebook's React Native 0.58 version. - 1. In terminal: e.g. `git branch fb58merge` - 2. In terminal: e.g. `git checkout fb58merge` -3. Pull the fb contents at the merge point we want. A list of their most recent versions can be found [here](https://facebook.github.io/react-native/versions). - 1. In terminal: e.g. `git fetch facebook v0.58.6` -4. Do the merge at the point we want, in this example it's the last version tag of their 0.58 build. Use the name you used in 3.1 here. - 1. In terminal: e.g. `git merge v0.58.6` - -## Integration Guidelines -It's likely you'll want to push the initial merge up to github **with** the merge conflicts. This makes it easier for other people to see where the errors are and help fix their platforms quickly. - -1. Commit all the changes (conflicts and all). There are many resources to do this such as the [Visual Studio Code](https://code.visualstudio.com/) UI or command line. -2. After you've committed all the changes, push your merge up. - 1. In terminal: `git push`. This should fail to push, but print out a suggested `git push [more repo specifics here]` command. - 2. Copy and run that suggested push command which has the proper upstream repo specified. - -#### First Time Merging? Read Below. Otherwise this shouldn't apply to you. -3. The first time doing this, terminal may ask for your github credentials after running the `git push` command from 2.2. You'll need to provide your github username and a 2-Factor-Authentication token password. If you don't have this yet, see substeps below. Github doesn't distinguish when you need to use your github password vs. this 2FA token, but for command line github interactions, you'll need to use the token. - 1. Generate your personal access token [here](https://github.com/settings/tokens) - 2. More details [here](https://stackoverflow.com/questions/29297154/github-invalid-username-or-password) - -## Best Practices -* Before pulling in a new React-Native version, verify with platform owners that they're ready to work on the merge. - * Why? - * This prevents merges from getting stuck in limbo where some platforms aren't done for multiple months and in the meantime we have to maintain two working branches. Faster we merge from start to finish, the exponentially less pain we incur. - * Platform owners - * Win32- acoates-ms - * Android- acoates-ms - * iOS- HeyImChris/tom-un - * Mac- HeyImChris/tom-un -* Make sure you're pulling in a **stable** [release candidate](https://facebook.github.io/react-native/versions). diff --git a/docs/Releases.md b/docs/Releases.md index 71478eac683623..ea078e46f8a68c 100644 --- a/docs/Releases.md +++ b/docs/Releases.md @@ -1,200 +1,3 @@ # Releases Guide -This document serves as guide for release coordinators. You can find a list of releases and their release notes at https://github.com/facebook/react-native/releases - -## Release schedule - -React Native follows a monthly release train. Every month, a new branch created off `main` enters the Release Candidate phase, and the previous Release Candidate branch is released and considered stable. - ------------------- - -## How to cut a new release branch - -### Prerequisites - -The following are required for the local test suite to run: - -- macOS with [Android dev environment set up](https://github.com/facebook/react-native/blob/HEAD/ReactAndroid/README.md) -- [react-native-cli](https://www.npmjs.com/package/react-native-cli) installed globally (v0.2.0 or newer) - -### Step 1: Check everything works - -Before cutting a release branch, make sure [Circle](https://circleci.com/gh/facebook/react-native) CI system is green. - -Before executing the following script, make sure you have: - -- An Android emulator / Genymotion device running -- No packager running in any of the projects - -```bash -./scripts/test-manual-e2e.sh -``` - -This script bundles a react-native package locally and passes it to the `react-native` cli that creates a test project inside `/tmp` folder using that version. - -After `npm install` completes, the script prints a set of manual checks you have to do to ensure the release you are preparing is working as expected on both platforms. - -### Step 2: Cut a release branch and push to GitHub - -Run: - -```bash -git checkout -b -stable -# e.g. git checkout -b 0.57-stable - -./scripts/bump-oss-version.js -v -# e.g. ./scripts/bump-oss-version.js -v 0.57.0-rc.0 -# or ./scripts/bump-oss-version.js -v 0.58.0 -``` - -Circle CI will automatically run the tests and publish to npm with the version you have specified (e.g `0.57.0-rc.0`) and tag `next` meaning that this version will not be installed for users by default. - -### Step 3: Write the release notes - -Write the release notes, or post in [React Native Core Contributors](https://www.facebook.com/groups/reactnativeoss/) that the RC is ready to find a volunteer. You can also use [react-native-release-notes](https://github.com/knowbody/react-native-release-notes) to generate a draft of release notes. - -To go through all the commits that went into a release, one way is to use the GitHub compare view: - -``` -https://github.com/facebook/react-native/compare/0.49-stable...0.50-stable -``` - -**Note**: This only shows **250** commits, if there are more use git. - -When making a list of changes, ignore docs, showcase updates and minor typos. - -Sometimes commit messages might be really short / confusing - try rewording them where it makes sense. Below are few examples: - -- `Fix logging reported by RUN_JS_BUNDLE` -> `Fix systrace logging of RUN_JS_BUNDLE event` -- `Fixes hot code reloading issue` -> `Fix an edge case in hot module reloading` - -Open a pull request against CHANGELOG.md at https://github.com/react-native-community/react-native-releases and ask for feedback. - -Once everything is ready, create a new release at https://github.com/facebook/react-native/releases and link to the release notes. - -**Important**: For release candidate releases, make sure to check "This is a pre-release". - -### Step 4: Update `Breaking Changes` document - -Once the release is cut, go to the [page](https://github.com/facebook/react-native/wiki/Breaking-Changes) where all breaking changes are listed and create section for the release. Don't forget to move all breaking changes from `main` that are now part of the release. - -When finished and there are breaking changes, include them in the release notes you just created. - -### Step 5: Tweet about the RC release - -Tweet about it! Link to release notes and say "please report issues" and link to the main issue to track bugs you created. - -### Step 6: IMPORTANT: Track bug reports from the community during the following month, ping owners to get them fixed - -Now that the release is out in the open, go ahead and create a GitHub issue titled "[[0.XX-RC] Commits to cherry-pick](https://github.com/facebook/react-native/issues/14713)" where 0.XX matches the release version. Use this issue to track bugs that have been reported for this particular release, including commits that should be cherry-picked in cases that a fix cannot wait until the next release. - -------------------- - -## How to release an RC update (e.g. 0.57.0-rc.1, 0.57.0-rc.2) - -The release is now in the open, people are finding bugs, and fixes have landed in `main`. People have been nominating fixes in the issue you created above. Use your best judgment to decide which commits merit an RC update. It's a good idea to do a new RC release when several small and non-risky bugs have been fixed. Having a few RC releases can also help people bisect in case we cherry-pick a bad commit by mistake. - -**Only cherry-pick small and non-risky bug fixes**. **Don't pick new features into the release** as this greatly increases the risk of something breaking. The main point of the RC is to let people to use it for a month and fix the most serious bugs. - - -### Step 1: Check out the release branch - -Follow these steps to check out the release branch: - -```bash -git checkout -stable -# e.g. git checkout 0.57-stable - -git pull origin -stable -# e.g. git pull origin 0.57-stable -``` - -> If you don't have a local checkout of the release branch, you can run the following instead: -> `git checkout -b -stable -t origin/-stable` - -### Step 2: Cherry-pick commits - -Now, cherry-pick those commits: - -``` -git cherry-pick commitHash1 -``` - -### Step 3: IMPORTANT: Test everything again (Chrome debugging, Reload JS, Hot Module Reloading) - -Go through the same process as earlier to test the release: - -``` -./scripts/test-manual-e2e.sh -``` - -### Step 4: Bump the version number - -If everything worked, run the following to bump the version number: - -```bash -./scripts/bump-oss-version.js -v -# e.g. ./scripts/bump-oss-version.js -v 0.57.0-rc.1 -``` - -Again, Circle CI will automatically run the tests and publish to npm with the version you have specified (e.g `0.57.0-rc.1`). - -### Step 5: Update the release notes - -Go to https://github.com/facebook/react-native/releases and find the release notes for this release candidate. Edit them so that they now point to the tag that you've just created. We want single release notes per version. For example, if there is v0.57.0-rc and you just released v0.57.0-rc.1, the release notes should live on the v0.57.0-rc.1 tag at https://github.com/facebook/react-native/tags - -------------------- - -## How to do the final stable release (e.g. 0.57.0, 0.57.1) - -A stable release is promoted roughly a month after the release branch is cut (refer to the schedule above). The release may be delayed for several reasons, including major issues in the release candidate. Make sure that all bug fixes that have been nominated in your tracking issue have been addressed as needed. Avoid cherry-picking commits that have not been vetted in the release candidate phase at this point. - -Once you are sure that the release is solid, perform the following steps. Note that they're similar to the steps you may have followed earlier when patching the release candidate, but we're not cherry-picking any additional commits at this point. - -### Step 1: Check out the release branch - -```bash -git checkout -stable -# e.g. git checkout 0.57-stable - -git pull origin -stable -# e.g. git pull origin 0.57-stable -``` - -> If you don't have a local checkout of the release branch, you can run the following instead: -> `git checkout -b -stable -t origin/-stable` - -### Step 2: IMPORTANT: Test everything again (Chrome debugging, Reload JS, Hot Module Reloading) - -It's **important** to test everything again: you don't want to cut a release with a major blocking issue! - -``` -./scripts/test-manual-e2e.sh -``` - -### Step 3: Bump the version number - -If everything worked: - -```bash -./scripts/bump-oss-version.js -v -# e.g. ./scripts/bump-oss-version.js -v 0.57.0 -``` - -As with the release candidate, Circle CI will automatically run the tests and publish to npm with the version you have specified (e.g `0.57.0`). - -Go to [Circle CI](https://circleci.com/gh/facebook/react-native) and look for the build triggered by your push (e.g. _0.57-stable, [0.57.0] Bump version numbers_), then scroll down to the npm publish step to verify the package was published successfully (the build will be red if not). - -This will now become the latest release, and will be installed by users by default. At this point, the website will be updated and the docs for this release will be displayed by default. - -### Step 4: Update the release notes - -Go to https://github.com/facebook/react-native/releases and find the release notes for this release candidate. Edit them so that they now point to the tag that you've just created. We want single release notes per version. For example, if there is v0.57.0 and you just released v0.57.1, the release notes should live on the v0.57.1 tag at https://github.com/facebook/react-native/tags - -For non-RC releases: Uncheck the box "This is a pre-release" and publish the notes. - -### Supporting the release - -Sometimes things don't go well and a major issue is missed during the release candidate phase. If a fix cannot wait until the next release is cut, it may be necessary to cherry-pick it into the current stable release. Go back to your `[0.XX-RC] Commits to cherry-pick` issue and rename it to `[0.XX] Commits to cherry-pick`, then add a comment stating that any cherry-pick requests from then on will be applied to the stable release. - -**The same guidelines for RC cherry-picks apply here. If anything, the bar for cherry-picking into a stable release is higher.** Stick to commits that fix blocking issues. Examples may be RedBoxes on newly generated projects, broken upgrade flows with no workaround, or bugs affecting the compiling and/or building of projects. +To be written. \ No newline at end of file diff --git a/docs/Android-Deforking.md b/docs/archive/Android-Deforking.md similarity index 100% rename from docs/Android-Deforking.md rename to docs/archive/Android-Deforking.md diff --git a/docs/hermes-jan-2020.md b/docs/archive/hermes-jan-2020.md similarity index 100% rename from docs/hermes-jan-2020.md rename to docs/archive/hermes-jan-2020.md diff --git a/docs/graphs/RNmacosGITFLOW.png b/docs/graphs/RNmacosGITFLOW.png new file mode 100644 index 00000000000000..f78184b83d0d93 Binary files /dev/null and b/docs/graphs/RNmacosGITFLOW.png differ diff --git a/docs/graphs/git-history-example.png b/docs/graphs/git-history-example.png new file mode 100644 index 00000000000000..00df1abbd15c41 Binary files /dev/null and b/docs/graphs/git-history-example.png differ