Rewrite Git workflow

Rewrite the Git workflow from the wiki and link to it in the contributing guide.

CONTRIBUTING.md

@@ -2,7 +2,7 @@
 
 Please be sure to branch from the head of the default branch when developing contributions.
 
-For our GitHub workflow, check out our [Wiki](https://github.com/App-vNext/Polly/wiki/Git-Workflow).
+For our GitHub workflow, check out our [documentation](https://www.pollydocs.org/community/git-workflow.html).
 
 Since Polly is part of the .NET Foundation, we ask our contributors to abide by their [Code of Conduct](https://www.dotnetfoundation.org/code-of-conduct). To contribute (beyond trivial typo corrections), review and sign the [.NET Foundation Contributor License Agreement](https://cla.dotnetfoundation.org/). This ensures the community is free to use your contributions.  The registration process can be completed entirely online.
 

docs/community/git-workflow.md

@@ -0,0 +1,49 @@
+# Git Workflow
+
+The general process for working with Polly is:
+
+1. [Fork](https://docs.github.com/get-started/quickstart/fork-a-repo) our repository on GitHub
+2. Clone your fork locally
+3. Configure the upstream (`git remote add upstream https://github.com/App-vNext/Polly.git`)
+4. Switch to the default branch (i.e. `main`) using `git checkout main`
+5. Create a new local branch for your changes (`git checkout -b my-branch`).
+6. Work on your changes
+7. Rebase if required (see below)
+8. Push the branch up to GitHub (`git push origin my-branch`)
+9. [Create a Pull Request][create-a-pr] on GitHub - the PR should target (have as base branch) the default branch (i.e. `main`).
+
+You should not work on a clone of the default branch, and you should not send a pull request from it - please always work from a branch. The reasons for this are detailed below.
+
+## Learning Git Workflow
+
+For an introduction to Git, check out [GitHub's _Git Guide_](https://github.com/git-guides). For more information about GitHub Flow, please head over to the [GitHub Flow](https://docs.github.com/get-started/quickstart/github-flow) documentation.
+
+## Handling Updates from the default branch
+
+While you're working away in your branch, it's possible that one or new commits have been added to the Polly repository's default branch. If this happens you should:
+
+1. [Stash](https://git-scm.com/book/en/v2/Git-Tools-Stashing-and-Cleaning) any uncommitted changes you need to
+2. `git checkout main`
+3. `git pull upstream main`
+4. `git checkout my-branch`
+5. `git rebase main`
+6. [Sync your fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork) (optional) - this this makes sure your remote main branch is up to date
+
+This ensures that your history is "clean" i.e. you have one branch off from `main` followed by your changes in a straight line. Failing to do this ends up with several "messy" merges in your history, which we don't want. This is the reason why you should always work in a branch and you should never be working in, or sending pull requests from, `main`.
+
+Rebasing public commits is [considered to be bad](https://git-scm.com/book/en/v2/Git-Branching-Rebasing#The-Perils-of-Rebasing), which is why we ask you to rebase any updates from `upstream/main`.
+
+If you're working on a long running feature then you may want to do this quite often, rather than run the risk of potential merge issues further down the line.
+
+## Sending a Pull Request
+
+While working on your feature you may well create several branches, which is fine, but before you send a pull request you should ensure that you have rebased back to a single "Feature branch" - we care about your commits, and we care about your feature branch; but we don't care about how many or which branches you created while you were working on it.
+
+When you're ready to go you should confirm that you are up to date and rebased with upstream (see _"Handling Updates from the default branch"_ above), and then:
+
+1. `git push origin my-branch`
+1. Send a descriptive [Pull Request][create-a-pr] on GitHub - making sure you have selected the correct branch in the GitHub UI.
+
+It is not the end of the world if the commit history in your pull request ends up being messy - we can always squash it down to a single commit before merging. However, if you follow the steps above you should end up with a neater history.
+
+[create-a-pr]: https://docs.github.com/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request

docs/index.md

@@ -43,5 +43,6 @@ You can also find many resources and community contributions, such as:
 - [Polly-Contrib](community/polly-contrib.md): Community projects and libraries that extend and enhance Polly's functionality and ecosystem.
 - [Libraries and contributions](community/libraries-and-contributions.md): Dependencies and contributors that make Polly possible and awesome.
 - Microsoft's [eShopOnContainers project](https://github.com/dotnet-architecture/eShopOnContainers): Sample project demonstrating a .NET Micro-services architecture and using Polly for resilience.
+- [Git Workflow](community/git-workflow.md): Our suggested Git workflow for contributing to Polly.
 
 You can browse the documentation using the sidebar or visit the [API](api/index.md) section for the reference documentation.

docs/toc.yml

@@ -66,6 +66,8 @@
     href: community/libraries-and-contributions.md
   - name: Useful resources and links
     href: community/resources.md
+  - name: Git workflow
+    href: community/git-workflow.md
 
 - name: API
   href: api/