diff --git a/website/contributing/how-to-contribute.md b/website/contributing/how-to-contribute.md new file mode 100644 index 00000000000..053a39e7f9a --- /dev/null +++ b/website/contributing/how-to-contribute.md @@ -0,0 +1,21 @@ +--- +title: How to contribute +description: React Native Community +--- + +# How to contribute to React Native + +Thank you for your interest in contributing to the React Native! From commenting on and triaging issues, to reviewing and sending Pull Requests, all contributions are welcome. We aim to build a vibrant and inclusive [ecosystem of partners, core contributors, and community](https://github.com/facebook/react-native/blob/main/ECOSYSTEM.md) that goes beyond the main React Native GitHub repository. + +The [Open Source Guides](https://opensource.guide/) website has a collection of resources for individuals, communities, and companies who want to learn how to run and contribute to an open source project. Contributors and people new to open source alike will find the following guides especially useful: + +- [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/) +- [Building Welcoming Communities](https://opensource.guide/building-community/) + +### Code of Conduct + +As a reminder, all contributors are expected to adhere to the [Code of Conduct](https://github.com/facebook/react/blob/main/CODE_OF_CONDUCT.md). + +## Ways to Contribute + +Please see our [Contributing Guide](https://github.com/facebook/react-native/blob/main/CONTRIBUTING.md) in the main React Native repository. diff --git a/website/contributing/release-candidate-minor.md b/website/contributing/release-candidate-minor.md new file mode 100644 index 00000000000..1d629b38ac9 --- /dev/null +++ b/website/contributing/release-candidate-minor.md @@ -0,0 +1,170 @@ +--- +id: release-candidate-minor +title: Release Minor Candidate +--- + +This document goes over steps to run different types of React Native release updates. It is intended audience is for those in relevant release roles. + +### Pre-requisites + +- Write access to [react-native](https://github.com/facebook/react-native) repository. +- Your CircleCI personal API token. See [here](https://circleci.com/docs/2.0/managing-api-tokens/#creating-a-personal-api-token) on how to set one. +- If testing, follow [pre-requisites for testing](/contributing/release-testing#pre-requisites). + +### Creating 0.{minor}.0-rc.0 + +- Create the release branch in `react-native` repo with the appropriate name (usually `0.X-stable`). + + ```bash + git checkout main + git pull origin main + git checkout -b 0.68-stable + git push origin 0.68-stable + + # This will walk you through what version you are releasing + ./scripts/bump-oss-version.js -v 0.68.0-rc.0 -t + ``` + +- Once you have run that script, head to CircleCI and you should see under the releases workflow, a `prepare-package-for-release` job. + +
+ CircleCI showing publish release +
CircleCI showing publish release.
+
+ +- This script runs and commits any changes and triggers a deploy job, `build_and_publish_npm_package`. +- Note: Look under “All Branches” to find the publish job. CircleCI does not give a way to search for these jobs. +- Once complete you should be able to run `npm view react-native` and verify `next` is expected release version. + + ```bash + npm view react-native + ... + dist-tags: + latest: 0.65.1 next: 0.66.0-rc.2 nightly: 0.0.0-f617e022c + ``` + +### 2. Create a PR of the changelog generator + +```bash +# Run following with the stable release as base, and your rc.0 version +npx @rnx-kit/rn-changelog-generator --base v[LATEST_STABLE]--compare v[YOUR_RC_0] \ +--repo ~/react-native --changelog ~/react-native/CHANGELOG.md > NEW_CHANGES.md + +# example against 0.66.4 and 0.67.0-rc.0 +npx @rnx-kit/rn-changelog-generator --base v0.66.4 --compare v0.67.0-rc.0 \ +--repo ~/react-native --changelog ~/react-native/CHANGELOG.md > NEW_CHANGES.md +``` + +- Prepend contents of `NEW_CHANGES.md` to `CHANGELOG.md`. +- Create a pull request of this change to `react-native` repo and add the `Changelog` label. + +### 3. Create a GitHub Release + +- Create a [GitHub Release](https://github.com/facebook/react-native/releases) with this template and **check “Pre-Release” checkbox**. + +```markdown + + +- + +--- + +To test it, run: + + + +npx react-native init RN067RC5 --version 0.67.0-rc.5 + +--- + +You can participate in the conversation on the status of this release in the [working group](https://github.com/reactwg/react-native-releases/discussions). + +--- + +To help you upgrade to this version, you can use the [upgrade helper](https://react-native-community.github.io/upgrade-helper/) ⚛️ + +--- + +See changes from this release in the [changelog PR](https://github.com/facebook/react-native/labels/%F0%9F%93%9D%20Changelog) +``` + +
+ Creating a GitHub Release +
Creating a GitHub Release.
+
+ +### 4. Create a tracking discussion post + +Create a "Road to " discussion post in [`react-native-releases`](https://github.com/reactwg/react-native-releases/discussions): + +```markdown + + + +The branch cut has happened. + +## Notice + + + +- [Current release candidate: 0.68.0-rc.0][current-release] +- Have an issue with current release candidate? [File an issue][issue-form] and we will triage. +- Have a pick request for this release? Does it fall under our [pick request qualifications][release-faq]? If so please create a PR against the release branch and comment with the PR link +- If you are release testing. Copy and fill [Test Checklist](/contributing/release-testing#test-checklist). + +#### Highlighted Changes in this release + + + +- Checkout this [Changelog PR][changelog-pr] + +## [Release Process][release-processes] + +#### Checklist + +- [ ] [Changelog PR][changelog-pr] +- [ ] Start a Google doc of blog post for release and invite contributors of release highlights to expand +- [ ] Follow up on [release dependencies][release-dependencies] + > When ready to publish stable +- [ ] Ship changelog +- [ ] Ship blog post +- [ ] Notify `react-native-website` to ship new version + +#### Retrospective Topics + + + +- + +## Release Status + +### Tracking 0.67.0-rc.1 + +#### Blocking issues for releasing 0.67.0-rc.1 + +- + +#### Picks for 0.67.0-rc.1 + +- + +[changelog-pr]: https://github.com/facebook/react-native/labels/%F0%9F%93%9D%20Changelog +[current-release]: https://github.com/facebook/react-native/releases +[changelog-wiki]: https://github.com/facebook/react-native/wiki/Release-Changelog +[release-dependencies]: https://reactnative.dev/contributing/release-dependencies +[release-faq]: https://reactnative.dev/contributing/release-faq +[issue-form]: https://github.com/facebook/react-native/issues/new?assignees=&labels=Needs%3A+Triage+%3Amag%3A%2Cpre-release&template=release_blocker_form.yml +[releases]: https://github.com/facebook/react-native/releases +[release-processes]: https://reactnative.dev/contributing/how-to +[upgrade-helper]: https://reactnative.dev/contributing/updating-upgrade-helper +``` + +### 5. Verify that Upgrade Helper GitHub action has fired + +- You should see a [new publish job complete here](https://github.com/react-native-community/rn-diff-purge/actions). +- If not, check out the guide on [how to update Upgrade Helper](/contributing/updating-upgrade-helper). + +### 6. Broadcast that release candidate is out + +- React Native Twitter. +- Discord `#releases-coordination` channel. diff --git a/website/contributing/release-candidate-patch.md b/website/contributing/release-candidate-patch.md new file mode 100644 index 00000000000..8c53a539a65 --- /dev/null +++ b/website/contributing/release-candidate-patch.md @@ -0,0 +1,25 @@ +--- +id: release-candidate-patch +title: Release Patch Candidate +--- + +### Pre-requisites + +- You have some pick requests that qualify for a patch release and people have agreed it’s good to release a patch. + +### 1. Check out the latest version from release branch and run `bump-oss-version` script + +```bash +# update the stable branch with tags +git pull origin --tags + +# cherry pick relevant commits +git cherry-pick + +# once done picking, run the script to release +./scripts/bump-oss-version.js +``` + +### 2. Similar to cutting new branch, watch CircleCI to ensure right jobs are being triggered + +### 3. Update the relevant discussion post with the latest RC diff --git a/website/contributing/release-dependencies.md b/website/contributing/release-dependencies.md new file mode 100644 index 00000000000..abb3f778522 --- /dev/null +++ b/website/contributing/release-dependencies.md @@ -0,0 +1,20 @@ +--- +id: release-dependencies +title: Release Dependencies +--- + +This table wants to highlight the various tooling that we need to pay attention to and potentially bump to ensure that everything works correctly - it could be that some versions need to be only changed/bumped in the [`template`](https://github.com/facebook/react-native/tree/main/template) folder. + +| Tool | Ping team ahead of branch cut? | Bump when... | Reference bump | Link to source | +| --------------------- |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | +| Metro | Yes, ping Meta's Metro team - a new version needs to be cut too. | During RC phase of new minor, coordinated with RN CLI (see below). | [link](https://github.com/facebook/react-native/commit/cfdc4fed0d0ba7860d176c1715c0cc84bea643af) | [source](https://github.com/facebook/metro/tags) | +| RN CLI | Yes, ping RN CLI maintainers - they need to do a new release that depends on new Metro version (from above), [like so](https://github.com/react-native-community/cli/pull/1442/files). | During RC phase of new minor, coordinated with Metro (see above). | [link](https://github.com/facebook/react-native/pull/31971/files) | [source](https://github.com/react-native-community/cli/tags) | +| Hermes | Yes, ping Meta's Hermes team - a new version needs to be cut too. | During RC phase of new minor - the closer to the commit of the branch cut, the better. | [link](https://github.com/facebook/react-native/commit/1d6af14d6d6e5a7e3a773b581600b01934a7d442) | [source](https://github.com/facebook/hermes/tags) | +| Flipper | No need, they release on their own schedule. | We just need to sync to the newest set of dependencies at the time of branch cut using this as [reference](https://github.com/facebook/flipper/blob/main/react-native/ReactNativeFlipperExample/ios/Podfile#L30). | [link](https://github.com/facebook/react-native/pull/31896) | [source](https://github.com/facebook/flipper/tags) | +| Folly | No need, they release on their own schedule. | Usually this dependency gets kept up to date by Meta's internal dev loop so it should be necessary to bump at release cut. But it needs to be the same version that is imported via Flipper (Flipper-Folly) to avoid issues. | [link](https://github.com/facebook/react-native/commit/b0c8a4eee821ca0b22e166a2a38f2bd2f22a1abe) | [source](https://github.com/facebook/folly/tags) | +| Jest | No need, they release on their own schedule. | This will be updated by the Meta engineers to stay aligned to the version used internally - so no relationship with the RN release cycle. | [link](https://github.com/facebook/react-native/commit/d6cd2e6559ff8698833dc277810e2e7e80af760a) | [source](https://github.com/facebook/jest/tags) | +| Android SDK | Out of our control. | Needs to be clarified (kept up to date by internal team?). | [link](https://github.com/facebook/react-native/pull/32606/files) | [source](https://developer.android.com/studio/releases/platforms) | +| Gradle | Out of our control. | Needs to be clarified (kept up to date by internal team? [example](https://github.com/facebook/react-native/commit/cd4c6659d3477a82f7bf14570ecdd6e9bfb9435e)). | [link](https://github.com/facebook/react-native/pull/32588) | [source](https://gradle.org/releases/) | +| Android Gradle Plugin | Out of our control. | Needs to be clarified (kept up to date by internal team? [example](https://github.com/facebook/react-native/commit/cd4c6659d3477a82f7bf14570ecdd6e9bfb9435e)). | [link](https://github.com/facebook/react-native/pull/32589) | [source](https://developer.android.com/studio/releases/gradle-plugin) | +| JSC | Out of our control. | Needs to be clarified. | [link](https://github.com/facebook/react-native/pull/31304) | [source](https://github.com/react-native-community/jsc-android-buildscripts/tags) | +| CocoaPods | Out of our control. | Needs to be clarified. | [link](https://github.com/facebook/react-native/commit/c6907ee488d938d227682605d7a6ce60f460bfc2) | [source](https://github.com/CocoaPods/CocoaPods/tags) | diff --git a/website/contributing/release-faq.md b/website/contributing/release-faq.md new file mode 100644 index 00000000000..5c88d19a123 --- /dev/null +++ b/website/contributing/release-faq.md @@ -0,0 +1,53 @@ +--- +id: release-faq +title: Release FAQ +--- + +### What is a qualified pick request? + +Judgement call, but using these dimensions to evaluate: + +- Is a fix for an issue introduced in current release. +- Fix for a critical developer workflow. + +### What is release blocking? + +Judgement call, but using these dimensions to evaluate: + +- Is it a new issue on the release candidate? +- Is it breaking a core experience of working in React Native? + +### What versions does the release community commit to supporting? + +We commit to handling issues on the current release and release candidate. +Any versions prior to this, we cannot commit to supporting. + +### When will my fix make it into a release? + +We follow a release cycle that is 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 `main` (e.g. `0.67-stable`), with all the merged commits up to this point. After this initial cut, new commits on `main` 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 `main` 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. + +### How do I know if my fix/feature is in a certain 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 `main` 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 '. + +Once you have the commit hash, navigate to `https://github.com/facebook/react-native/commit/`. 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 [a6768bfd70187634e587d7b2e92d2b6735a4037e](https://github.com/facebook/react-native/commit/a6768bfd70187634e587d7b2e92d2b6735a4037e) has the following tags as of this writing: +```plain +v0.67.0-rc.3 v0.67.0-rc.2 v0.67.0-rc.1 v0.67.0-rc.0 v0.66.3 v0.66.2 v0.66.1 v0.66.0 v0.66.0-rc.4 v0.66.0-rc.3 v0.66.0-rc.2 v0.66.0-rc.1 v0.66.0-rc.0 latest +``` +These tags tell us that the commit first made it into the 0.66 release candidate, eventually landing in the 0.66 stable release. It is also present, as you'd expect, in the 0.67 release candidate (and should make it to 0.67 stable, and so on). + +If the commit is only present in `main` (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. + +### How can I find the status of the current release? + +We have a dedicated [release discussions repo](https://github.com/reactwg/react-native-releases/discussions). We have a category for [new releases](https://github.com/reactwg/react-native-releases/discussions/categories/releases) and one for [patches](https://github.com/reactwg/react-native-releases/discussions/categories/patches). + +- For a new release version, we track the status of each new release candidate patch with any ongoing blocking issues and checklist of work. [Example of releasing 0.67](https://github.com/reactwg/react-native-releases/discussions/1) +- For patches, a discussion is opened asking whether there are picks that qualify to run a patch (see qualifying picks). People can comment and share any picks from main and the release captain will run a patch when necessary and subsequently open a new discussion for the next patch version. Example of [discussion for 0.66.4](https://github.com/reactwg/react-native-releases/discussions/6), once it was released, the discussion is locked and a discussion for 0.66.5 is opened. + +### What if I find a release blocker that needs escalation? + +- Is there an existing release blocking issue? + - If no, [create a release blocking issue via this form](https://github.com/facebook/react-native/issues/new?assignees=&labels=Needs%3A+Triage+%3Amag%3A%2CType%3A+Upgrade+Issue&template=upgrade-regression-form.yml). +- Once you have a release blocking issue, share the issue with the [relevant release discussion](https://github.com/reactwg/react-native-releases/discussions). diff --git a/website/contributing/release-roles-responsibilites.md b/website/contributing/release-roles-responsibilites.md new file mode 100644 index 00000000000..df7974548ee --- /dev/null +++ b/website/contributing/release-roles-responsibilites.md @@ -0,0 +1,134 @@ +--- +id: release-roles-responsibilities +title: Roles and Responsibilities +--- + +Here we set guidelines to apply the “dividi et impera” approach to React Native releases: it is an involved process and we need to clarify the work to allow for easier rotations of folks in various positions. + +The roles should be imagined as “concentric”, with #1 in the centre: this means that anything in role #3 can be done by #2 or #1, and anything on role #2 can be done by #1. + +The goal of this structure is that #1 doesn’t have to do everything: to do so the suggestion is to at least always have a person per each role in each release. + +--- + +## Release Role #1: Meta Releasers (x2) + +### Details + +Two sub-roles: + +- 1 **release captain** as main point of contact per minor release (aiming for every 2 months, see [schedule](https://github.com/facebook/react-native/wiki/Release-Schedule)) +- 1 **reverse shadow** per minor release — working on high-need tooling (perhaps from retrospective of previous minor release) and serves as backup if release captain is out + +**Time commitment:** maximum 4 hours/week of work for each release captain and reverse shadow. + +### Release Captain Responsibilities + +- Drives the initial cut and sets up release scaffolding (re: blogpost draft, documentation bump, etc) +- Is informed of the pre-release & stable release status and any blocking issues and communicates to appropriate channels + - Attends & drives weekly release meeting + - updates and monitors the #releases channel + - updates and monitors discussion in [react-wg/react-native-releases](https://github.com/reactwg/react-native-releases/discussions) discussion for both: + - the [pre-release](https://github.com/reactwg/react-native-releases/discussions/categories/releases) + - the [stable release (for patches)](https://github.com/reactwg/react-native-releases/discussions/categories/patches) +- Make final call on release decisions + - Decide when to promote pre-release to stable (in consult with **co-pilot** and **release supporters**) + - Decide when to release a patch on stable +- Ensures blocking issues have owners + - Escalate internally if release community is blocked by Meta-owned dependencies (metro, folly, flipper, hermes, etc) + - Coordinate with release co-pilot & supporters on any community library blockers (reanimated, cli, etc.) +- Escalates security alerts + - When a security alert gets raised, communicates it quickly to relevant partners and internally + - If the security fix commit lands and it’s important, coordinates with the **copilot** on which stable branches should get the releases and produces the patch releases accordingly +- Can perform release or delegate release steps (as well as **release co-pilot/reverse shadow**) + +### Reverse Shadow Responsibilities + +- Is informed of the minor release status and current stable status +- Supports release captain + - Fills in for release captain if current release captain is unavailable +- Actions on high-priority tooling, retrospective action items when relevant + +### Who can fill it + +- These roles must be filled by Meta engineers + +--- + +## Release Role #2 : Release Copilot + +### Details + +- 1 or 2 people (the second one being backup) + +**Time commitment:** can be more flexible and doesn’t have to align with minor release schedule, but we should update the release schedule when needed. Most likely, a couple hours per week. + +### Responsibilities + +- Is informed of the minor release status and current stable status + - attends weekly release meeting + - updates and monitors #releases channel + - updates and monitors discussion in [react-wg/react-native-releases](https://github.com/reactwg/react-native-releases/discussions) discussion for both: + - the [pre-release](https://github.com/reactwg/react-native-releases/discussions/categories/releases) + - the [stable release (for patches)](https://github.com/reactwg/react-native-releases/discussions/categories/patches) +- Ensures blocking issues have owners + - Escalate to Meta releaser when blocked by Meta-owned dependencies (metro, folly, flipper, hermes, etc) + - Find owners, coordinate with Meta releaser for any community library blockers (reanimated, cli, etc.) +- Support release decisions + - Help decide when to promote pre-release to stable + - Help decide when to release a patch on stable + - Help decide which commits are part of which release +- Can perform release (pre-release/stable) + - Merge cherry-picks (as agreed with main releaser) + - Create the changelog & release entry in GH + - Makes documentation PR and blogpost PR + - Trigger the rn-diff-purge script to update upgrade-helper (this should be automated for 0.68 onwards) +- Help release testing via [local E2E script](/contributing/release-testing) + +### Who can fill it + +- This role can be filled by anyone with write access to the necessary repos (react-native) + +--- + +## Release Role #3: Release Supporter + +### Details + +- 0 to N **release supporters** +- 0 to N **release testers** + +**Time commitment:** as much or as little as available by each person. + +No strict coupling with any specific release - active supports and testers will be thanked in the release notes of versions they help with. + +### Release Supporter Responsibilities + +- Surface release issues either on stable or release candidate by triaging [release issues in the react-native repo](https://github.com/facebook/react-native/labels?q=release) + - Some issues might not be tagged appropriately, so keep an eye out on incoming issues and surface any +- Watch the [release discussions repo](https://github.com/reactwg/react-native-releases/discussions) + - Help answer/debug/escalate issues +- Work on any [release improvements](https://github.com/facebook/react-native/projects/18) or if you see something that can be improved; please add! +- Help [test release candidates](/contributing/release-testing) with your configuration or improve it +- Engage/help out with discussion in the release related channels (#supporters-feed, #testers-feedback, #release-coordination) + +### Release Tester Responsibilities + +This role is about helping test release candidates against your production app/workflows + +- Helps surface release issues either on stable or release candidate by them testing out against their production apps and workflows + - Perhaps integrate either the [npm `next` or `nightly` versions of react-native](https://www.npmjs.com/package/react-native) in your app's CI and raise any issues that might come up. +- Support regression fixes if relevant +- Engage/help out with discussion in the release related channels (#supporters-feed, #testers-feedback, #release-coordination) + +### Who can fill it + +- Anyone interested in supporting the React Native Open Source project and its releases! + - To start, you can participate in the [discussion repo](https://github.com/reactwg/react-native-releases/discussions) -- testing release candidates, surfacing any release issues you've seen or encountered yourself + - We also have some [discussions about improvements](https://github.com/reactwg/react-native-releases/discussions/categories/improvements) here as well as some issues related to [improving the release process in this project board](https://github.com/facebook/react-native/projects/18). + - If you are up for any specific tasks, let us know by commenting on it. +- For release testers, it's preferred (as it's very valuable) that you are able to test the releases against a production app in order to also verify non-trivial parts of the flow like archiving a release for the App Store. + +#### Apply to the role + +For both supporters and testers, you can let us know that you want to help out in this [dedicated discussion](https://github.com/reactwg/react-native-releases/discussions/11). We will provide you access to a dedicated RN Discord server that folks involved the releasers use to coordinate. diff --git a/website/contributing/release-stable-minor.md b/website/contributing/release-stable-minor.md new file mode 100644 index 00000000000..f9d95f3b0d1 --- /dev/null +++ b/website/contributing/release-stable-minor.md @@ -0,0 +1,73 @@ +--- +id: release-stable-minor +title: Release Stable Minor +--- + +### Pre-requisites + +- Have the blog post ready to submit as a PR for `react-native-website` [repository](https://github.com/facebook/react-native-website). +- Changelog PR should be ready to merge. + +### 1. Publish the release + +```bash +# In your react-native checkout, on the release branch of the version +./scripts/bump-oss-version.js +> What version are you releasing? +# Your version +> Do you want this to be latest? +# Generally yes. This updates npm registry to point to this version as "latest" +``` + +### 2. Update the GitHub releases + +- You can find out how many commits and contributors for a release by making a PR and [comparing the release branches](https://github.com/facebook/react-native/compare/0.66-stable...0.67-stable). + +```markdown + + +0.66 stable is out! + +This release includes **621 commits** with **92 contributors**! Thank you to all our contributors new and old! You can find the [full changelog here](https://github.com/react-native-community/releases/blob/master/CHANGELOG.md#v0660). + +- See the highlights of the release in our [release blog post](https://reactnative.dev/blog/2021/10/01/version-066). +- You can participate in the conversation on the status of this release at [this issue](https://github.com/react-native-community/releases/issues/254). +- You can upgrade to this version using the [upgrade helper webtool](https://react-native-community.github.io/upgrade-helper/) ⚛️ +``` + +### 3. Create a new patch post for your new version + +```markdown +## Should we release 0.67.1? + +Current Release: 0.67.0 + +Conversations on this thread are limited: + +- [major release issues](https://reactnative.dev/contributing/release-faq#what-is-release-blocking). +- [qualified cherry-pick requests](https://reactnative.dev/contributing/release-faq#what-is-a-qualified-pick-request) of commits on main that [did not make the previous patch version](https://reactnative.dev/contributing/release-faq#how-do-i-know-if-my-fixfeature-is-in-a-certain-release). + +Please include a link to the specific commit on main to be cherry-picked, for example: [facebook/react-native@bd2b7d6](https://github.com/facebook/react-native/commit/20b0eba581a00e5e7e300f6377379b836617c147) + +In other words, if you cannot point to a particular commit on main, then your request likely belongs as a new issue. +If the issue is a [major release issues](https://reactnative.dev/contributing/release-faq#what-is-release-blocking), please reference the issue here. + +--- + +#### List of qualified picks + +1. + +#### Local commits to backport to main + +1. +``` + +### 4. Close any outstanding patch posts for previous versions + +- Any patch posts for the previous stable are irrelevant now. + +### 5. Communicate the new release + +- Ship the `react-native-website` changes if not done already. +- Ship the blog post, tweet about blog post. diff --git a/website/contributing/release-stable-patch.md b/website/contributing/release-stable-patch.md new file mode 100644 index 00000000000..4dc7ae65514 --- /dev/null +++ b/website/contributing/release-stable-patch.md @@ -0,0 +1,84 @@ +--- +id: release-stable-patch +title: Release Stable Patch +--- + +### Pre-requisites + +- You have some pick requests that qualify for a patch release and people have agreed it’s good to release a patch. + +### 1. Cherry-pick commits and run `bump-oss-version` script + +```bash +# Be on relevant release branch +# update the stable branch with tags +git pull origin --tags + +# cherry pick relevant commits +git cherry-pick + +# once done picking, run the script to release +# You most likely want this release marked as "latest" +./scripts/bump-oss-version.js +``` + +### 2. Verify Upgrade helper is updated + +- You should see a [new publish job complete here](https://github.com/react-native-community/rn-diff-purge/actions). +- If not, check out the guide on [how to update Upgrade Helper](/contributing/updating-upgrade-helper). + +### 3. Create a new patch discussion post using template below + +```markdown + + +# Should we release 0.67.1? + +Current Release: [0.67.0](https://github.com/facebook/react-native/releases/tag/v0.67.0) + +Conversations on this thread are limited: +- [major release issues](https://reactnative.dev/contributing/release-faq#what-is-release-blocking). +- [qualified cherry-pick requests](https://reactnative.dev/contributing/release-faq#what-is-a-qualified-pick-request) of commits on main that [did not make the previous patch version](https://reactnative.dev/contributing/release-faq#how-do-i-know-if-my-fixfeature-is-in-a-certain-release). + +Please include a link to the specific commit on main to be cherry-picked, for example: [facebook/react-native@bd2b7d6](https://github.com/facebook/react-native/commit/20b0eba581a00e5e7e300f6377379b836617c147) + +In other words, if you cannot point to a particular commit on main, then your request likely belongs as a new issue. +If the issue is a [major release issues](https://reactnative.dev/contributing/release-faq#what-is-release-blocking), please reference the issue here. + +--- + +#### List of qualified picks + +1. + +#### Local commits to backport to main +1. +``` + +### 4. Update previous discussion post + +- Label it `Released`. +- Update the title saying the patch has been released and link to new patch discussion. +- Lock the discussion. + +### 5. Create GitHub Release + +Use template below for the GitHub Release: + +```markdown + + +- TODO Enumerate picks ( you can run `npx @rnx-kit/rn-changelog-generator single -c ` to generate markdown + +--- + +You can participate in the conversation on the status of this release at this [discussion](TODO: your discussion link) + +--- + +To help you upgrade to this version, you can use the [upgrade helper](https://react-native-community.github.io/upgrade-helper/) ⚛️ + +--- + +You can find the whole changelog history in the [changelog.md file](https://github.com/facebook/react-native/blob/main/CHANGELOG.md). +``` diff --git a/website/contributing/release-testing.md b/website/contributing/release-testing.md new file mode 100644 index 00000000000..6a0d84bb851 --- /dev/null +++ b/website/contributing/release-testing.md @@ -0,0 +1,123 @@ +--- +id: release-testing +title: How to test a release candidate +--- + +## Pre-requisites + +- Have clone of `react-native` repo and be on the release candidate branch. + + ```bash + # Checkout relevant branch + react-native$ git checkout 0.66-stable + react-native$ yarn install + + # I needed a .watchmanconfig because `npm start` would fail without it. + react-native$ echo '{}' > .watchmanconfig + ``` + +- Have Android and iOS development environment set-up. Follow instructions for macOS/iOS and macOS/Android from the [Environment Setup](/docs/environment-setup) guide. + + ### Additional steps for Android + - Gradle should now install [the appropriate ndk](https://github.com/facebook/react-native/blob/31b64c2615f8af547b68aa6ccaaa244b9c5d3932/template/android/build.gradle#L9). Verify that you have in your path the `ANDROID_NDK` variable, pointing to it. + - In case you are on macOS Catalina (or higher), you might also need to run `sudo xattr -r -d com.apple.quarantine /path/to/ndk` to avoid the e2e script to fail. That said, this should not happen anymore since from NDK 21 and higher the Android team started signing the NDK.\* + +## Test Dimensions + +Covered by running `test-manual-e2e.sh`, see [issue](https://github.com/facebook/react-native/issues/33015) about supporting those "manual" cases. + +| Variant | RNTester | Template App | +| ---------------- | ------------------------ | ------------------------ | +| Android - JSC | via `test-manual-e2e.sh` | via `test-manual-e2e.sh` | +| Android - Hermes | via `test-manual-e2e.sh` | manual | +| iOS - JSC | via `test-manual-e2e.sh` | via `test-manual-e2e.sh` | +| iOS - Hermes | via `test-manual-e2e.sh` | manual | + +## Test Checklist + +| Link to branch: | | +| ---------------------------- | :---------------------- | +| **Project info** | | +| Name | | +| Starting RN version | | +| Hermes on iOS | yes/no | +| Hermes on Android | yes/no | +| **Tested - iOS** | | +| Fast Refresh | ✅/🚨/🙅‍♂️ | +| Debug/dev build on Simulator | ✅/🚨/🙅‍♂️ | +| Debug/dev build on Device | ✅/🚨/🙅‍♂️ | +| Production build | ✅/🚨/🙅‍♂️ | +| Chrome remote debugger | ✅/🚨/🙅‍♂️ | +| Hermes debugger | ✅/🚨/🙅‍♂️ | +| Flipper debugger | ✅/🚨/🙅‍♂️ | +| **Tested - Android** | | +| Fast Refresh | ✅/🚨/🙅‍♂️ | +| Debug/dev build on Emulator | ✅/🚨/🙅‍♂️ | +| Debug/dev build on Device | ✅/🚨/🙅‍♂️ | +| Production build | ✅/🚨/🙅‍♂️ | +| Chrome remote debugger | ✅/🚨/🙅‍♂️ | +| Hermes debugger | ✅/🚨/🙅‍♂️ | +| Flipper debugger | ✅/🚨/🙅‍♂️ | + +## Steps + +1. Delete `RNTester` and `RNTestProject` from your Android emulator and iOS simulator if leftover from previous test. +2. Remove any temporary files: + ```bash + git clean -fdx + ``` + +3. Install dependencies: + ```bash + yarn install + pushd packages/rn-tester + pod install --repo-update + popd + ``` + +4. Go through **Test Checklist** for variants supported by `test-manual-e2e` script: + + ```bash + # This will run you through the different variants in Test Dimensions table + react-native$ ./scripts/test-manual-e2e.sh + ``` + +5. Go through **Test Checklist** for Hermes enabled template app. + + :::info + + Note: Script will install template app at `/tmp/RNTestProject`. + + ::: +- Enable Hermes for Android template app, clean, build and go through [Test Checklist](#test-checklist). + + ```bash + # Update `/tmp/RNTestProject/android/app/build.gradle` to `enableHermes` + project.ext.react = [ + enableHermes: true, // clean and rebuild if changing + ] + + # Clean and rebuild + /tmp/RNTestProject/android$ ./gradlew clean + /tmp/RNTestProject$ npx react-native run-android + ``` + +- Enable Hermes for iOS template app, clean, build and go through [Test Checklist](#test-checklist). + + ```bash + # Update `/tmp/RNTestProject/ios/Podfile` and then run `pod install` + use_react_native!( + :path => config[:reactNativePath], + # to enable hermes on iOS, change `false` to `true` and then install pods + :hermes_enabled => true + ) + + # Install pods and run + /tmp/RNTestProject/ios$ pod install + /tmp/RNTestProject$ npx react-native run-ios + ``` + +## Other dimensions to consider + +- Running your iOS project with `--release` configuration. +- Attempting to upload your app to TestFlight. diff --git a/website/contributing/release-troubleshooting.md b/website/contributing/release-troubleshooting.md new file mode 100644 index 00000000000..fcf71326b29 --- /dev/null +++ b/website/contributing/release-troubleshooting.md @@ -0,0 +1,44 @@ +--- +id: release-troubleshooting +title: Troubleshooting +--- + +### Manually set npm tags + +Say you accidentally forgot to mark a release as "latest" or "next"? + +```bash +# You'll need to first login: +npm login + +# Add a tag to a version +npm dist-tag add @ [] + +# Remove a tag to a version +npm dist-tag rm @ + +# List tags for react-native +npm dist-tag ls [] + +# Example of setting latest to 0.66.4 +npm dist-tag add react-native@0.66.4 latest +``` + +### Add Git Tags + +Say you accidentally forgot to add a tags to the release? + +```bash +# Delete a tag (annotated or not) locally, then push to delete it remotely +git tag --delete tagname +git push origin :tagname + +# Add an annotated tag +git tag -a v0.65.3 -m "whatever message" + +# Make sure you pull with tags +git pull --tags + +# Make sure you push any local tags you added/removed +git push --follow-tags +``` diff --git a/website/contributing/updating-upgrade-helper.md b/website/contributing/updating-upgrade-helper.md new file mode 100644 index 00000000000..2f0f09bf4c1 --- /dev/null +++ b/website/contributing/updating-upgrade-helper.md @@ -0,0 +1,50 @@ +--- +id: updating-upgrade-helper +title: How to Update Upgrade Helper +--- + +_Point people: [@lucasbento](https://github.com/lucasbento), [@pvinis](https://github.com/pvinis), [@kelset](https://github.com/kelset)_ + +From the readme of [its dedicated repo](https://github.com/react-native-community/upgrade-helper#-how-it-works): + +:::note + +The Upgrade Helper tool aims to provide the full set of changes happening between any two versions, based on the previous work done in the `rn-diff-purge` project: + +This repository exposes an untouched React Native app generated with the CLI `react-native init RnDiffApp`. Each new React Native release causes a new project to be created, removing the old one, and getting a diff between them. This way, the diff is always clean, always in sync with the changes of the init template. + +::: +The upgrade helper webapp relies on [rn-diff-purge](https://github.com/react-native-community/rn-diff-purge) having the diff for the versions of RN released. + +## Instructions to update + +### For release versions >= 0.68 + +- The GitHub action will be triggered by the [CircleCI job that pushes the release link](https://github.com/facebook/react-native/blob/main/.circleci/config.yml#L822). + +### For release versions < 0.68 + +:::caution + +You need to have write access or be a Code Owner for the `rn-diff-purge` repo to do either of these approaches. + +::: + +#### Trigger GitHub action via CURL + +```bash +# Update the "version" with your version and provide your PAT +curl -X POST -H "Accept: application/vnd.github.v3+json" \ + https://api.github.com/repos/react-native-community/rn-diff-purge/dispatches \ + -d '{"event_type":"publish", "client_payload": {"version": "0.67.0"}}' \ + -H "authorization: Bearer " +``` + +#### Manual instructions + +To generate the diff for a new version, there are essentially only 3 steps needed: + +- `git clone` the `rn-diff-purge` repo. +- `cd` into it, and `yarn install`. +- Run the script `./new-release.sh `. + - For example: `./new-release.sh 0.66.0-rc.1`. diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index c66b9c2b45a..673a3392fe6 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -148,6 +148,21 @@ const lastVersion = versions[0]; ], }, ], + [ + 'content-docs', + /** @type {import('@docusaurus/plugin-content-docs').Options} */ + ({ + id: 'contributing', + path: 'contributing', + routeBasePath: 'contributing', + sidebarPath: require.resolve('./sidebarsContributing.json'), + showLastUpdateAuthor: false, + showLastUpdateTime: true, + editUrl: + 'https://github.com/facebook/react-native-website/blob/master/website/', + remarkPlugins: [require('@react-native-website/remark-snackplayer')], + }), + ], ], themeConfig: /** @type {import('@docusaurus/preset-classic').ThemeConfig} */ @@ -206,8 +221,8 @@ const lastVersion = versions[0]; position: 'right', }, { - to: '/help', - label: 'Community', + to: '/contributing/how-to-contribute', + label: 'Contributing', position: 'right', }, { diff --git a/website/sidebarsContributing.json b/website/sidebarsContributing.json new file mode 100644 index 00000000000..b35cec90469 --- /dev/null +++ b/website/sidebarsContributing.json @@ -0,0 +1,37 @@ +{ + "contributing": [ + { + "type": "category", + "label": "Contributing to React Native", + "collapsed": false, + "collapsible": false, + "items": ["how-to-contribute"] + }, + { + "type": "category", + "label": "How to Perform Releases", + "collapsed": false, + "collapsible": false, + "items": [ + "release-candidate-minor", + "release-candidate-patch", + "release-stable-patch", + "release-stable-minor", + "release-troubleshooting" + ] + }, + { + "type": "category", + "label": "Release Guides", + "collapsed": false, + "collapsible": false, + "items": [ + "release-roles-responsibilities", + "release-dependencies", + "release-testing", + "updating-upgrade-helper", + "release-faq" + ] + } + ] +}