chore(docs): Update contributing docs

Author: chaance

docs/contributing.md

@@ -9,6 +9,29 @@ Thanks for contributing, you rock!
 
 When it comes to open source, there are many different kinds of contributions that can be made, all of which are valuable. Here are a few guidelines that should help you as you prepare your contribution.
 
+## Setup
+
+Before you can contribute to the codebase, you will need to fork the repo. This will look a bit different depending on what type of contribution you are making:
+
+- All new features, bug-fixes, or **anything that touches `react-router` code** should be branched off of and merged into the `dev` branch
+- Changes that only touch documentation can be branched off of and merged into the `main` branch
+
+The following steps will get you setup to contribute changes to this repo:
+
+1. Fork the repo (click the <kbd>Fork</kbd> button at the top right of [this page](https://github.com/remix-run/react-router))
+2. Clone your fork locally
+
+```bash
+# in a terminal, cd to parent directory where you want your clone to be, then
+git clone https://github.com/<your_github_username>/react-router.git
+cd react-router
+
+# if you are making *any* code changes, make sure to checkout the dev branch
+git checkout dev
+```
+
+3. Install dependencies and build. React Router uses [`yarn` (version 1)](https://classic.yarnpkg.com/lang/en/docs/install), so you should too. If you install using `npm`, unnecessary `package-lock.json` files will be generated.
+
 ## Think You Found a Bug?
 
 Please conform to the issue template and provide a clear path to reproduction with a code example. Best is a pull request with a failing test. Next best is a link to CodeSandbox or repository that illustrates the bug.
@@ -23,11 +46,13 @@ We have learned by experience that small APIs are usually better, so we may be a
 
 If you need a bug fixed and nobody is fixing it, your best bet is to provide a fix for it and make a [pull request](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request). Open source code belongs to all of us, and it's all of our responsibility to push it forward.
 
-Issues with no activity for 60 days will be automatically closed, with a warning 7 days before closing.
-
 ## Making a Pull Request?
 
-Pull requests need only the :+1: of two or more collaborators to be merged; when the PR author is a collaborator, that counts as one.
+Pull requests need only the approval of two or more collaborators to be merged; when the PR author is a collaborator, that counts as one.
+
+> **Important:** When creating the PR in GitHub, make sure that you set the base to the correct branch. If you are submitting a PR that touches any code, this should be the `dev` branch. You set the base in GitHub when authoring the PR with the dropdown below the "Compare changes" heading:
+>
+> <img src="../static/base-branch.png" alt="" width="460" height="350" />
 
 ### Tests
 
@@ -39,37 +64,115 @@ All commits that fix bugs or add features need a test.
 
 All commits that change or add to the API must be done in a pull request that also updates all relevant examples and docs.
 
-## Setup
+## Development
 
-The following steps will get you setup to contribute changes to this repo:
+### Packages
+
+React Router uses a monorepo to host code for multiple packages. These packages live in the `packages` directory.
 
-1. Fork the repo (click the <kbd>Fork</kbd> button at the top right of [this
-   page](https://github.com/remix-run/react-router))
+We use [Yarn workspaces](https://classic.yarnpkg.com/en/docs/workspaces/) to manage installation of dependencies and running various scripts. To get everything installed, make sure you have [Yarn (version 1) installed](https://classic.yarnpkg.com/lang/en/docs/install), and then run `yarn` or `yarn install` from the repo root.
 
-2. Clone your fork locally
+### Building
+
+Calling `yarn build` from the root directory will run the build, which should take only a few seconds. It's important to build all the packages together because `react-router-dom` and `react-router-native` both use `react-router` as a dependency.
+
+### Testing
+
+Before running the tests, you need to run a build. After you build, running `yarn test` from the root directory will run **every** package's tests. If you want to run tests for a specific package, use `yarn test --projects packages/<package-name>`:
 
 ```bash
-# in a terminal, cd to parent directory where you want your clone to be, then
-git clone https://github.com/<your_github_username>/react-router.git
-cd react-router
+# Test all packages
+yarn test
+
+# Test only react-router-dom
+yarn test --projects packages/react-router-dom
 ```
 
-3. Install dependencies and build. React Router uses `yarn` (version 1), so you
-   should too. If you install using `npm`, unnecessary `package-lock.json` files
-   will be generated.
+## Repository Branching
 
-## Development
+This repo maintains separate branches for different purposes. They will look something like this:
 
-### Packages
+```
+- main   > the most recent release and current docs
+- dev    > code under active development between stable releases
+- v5     > the most recent code for a specific major release
+```
 
-React Router uses a monorepo to host code for multiple packages. These packages live in the `packages` directory.
+There may be other branches for various features and experimentation, but all of the magic happens from these branches.
 
-We use [Yarn workspaces](https://legacy.yarnpkg.com/en/docs/workspaces/) to manage installation of dependencies and running various scripts. To get everything installed, just run `yarn` or `yarn install` from the repo root.
+## New Releases
 
-### Building
+When it's time to cut a new release, we follow a process based on our branching strategy depending on the type of release.
 
-Calling `yarn build` from the root directory will run the build, which should take only a few seconds. It's important to build all the packages together because `react-router-dom` and `react-router-native` both use `react-router` as a dependency.
+### `react-router@next` Releases
 
-### Testing
+We create experimental releases from the current state of the `dev` branch. They can be installed by using the `@next` tag:
+
+```bash
+yarn add react-router-dom@next
+# or
+npm install react-router-dom@next
+```
+
+These releases will be automated as PRs are merged into the `dev` branch.
+
+### Latest Major Releases
+
+```bash
+# Start from the dev branch.
+git checkout dev
 
-Before running the tests, you need to run a build. After you build, running `yarn test` from the root directory will run **every** package's tests. If you want to run tests for a specific package, use e.g. `jest --projects package/react-router`.
+# Merge the main branch into dev to ensure that any hotfixes and
+# docs updates are available in the release.
+git merge main
+
+# Create a new release branch from dev.
+git checkout -b release/v6.1.0
+
+# Create a new tag and update version references throughout the
+# codebase.
+yarn run version minor # | "patch" | "major"
+
+# Push the release branch along with the new release tag.
+git push origin release/v6.1.0 --follow-tags
+
+# Wait for GitHub actions to run all tests. If the tests pass, the
+# release is ready to go! Merge the release branch into main and dev.
+git checkout main
+git merge release/v6.1.0
+git checkout dev
+git merge release/v6.1.0
+
+# The release branch can now be deleted.
+git branch -D release/v6.1.0
+git push origin --delete release/v6.1.0
+
+# Now go to GitHub and create the release from the new tag. Let
+# GitHub Actions take care of the rest!
+```
+
+### Hot-fix Releases
+
+Sometimes we have a crucial bug that needs to be patched right away. If the bug affects the latest release, we can create a new version directly from `main` (or the relevant major release branch where the bug exists):
+
+```bash
+# From the main branch, make sure to run the build and all tests
+# before creating a new release.
+yarn && yarn build && yarn test
+
+# Assuming the tests pass, create the release tag and update
+# version references throughout the codebase.
+yarn run version patch
+
+# Push changes along with the new release tag.
+git push origin main --follow-tags
+
+# In GitHub, create the release from the new tag and it will be
+# published via GitHub actions
+
+# When the hot-fix is done, merge the changes into dev and clean
+# up conflicts as needed.
+git checkout dev
+git merge main
+git push origin dev
+```