Git Workflow

Git Workflow

ℹ️ This documentation describes the previous Polly v7 API. If you are using the new v8 API, please refer to pollydocs.org.

The general process for working with Polly is:

1. Fork on GitHub
2. Make sure your line endings are correctly configured
3. Clone your fork locally
4. Configure the upstream repo (git remote add upstream git://github.com/App-vNext/Polly)
5. Switch to the default branch (e.g. main, using git checkout main)
6. Create a local branch from that (git checkout -b myBranch).
7. Work on your feature
8. Rebase if required (see below)
9. Push the branch up to GitHub (git push origin myBranch)
10. Send a Pull Request on GitHub - the PR should target (have as base branch) the default branch (e.g. main).

You should never work on a clone of the default branch, and you should never send a pull request from it - always from a branch. The reasons for this are detailed below.

Learning Git Workflow

For an introduction to Git, check out GitHub Guides. For more information about GitHub Flow, please head over to the Understanding the GitHub Flow illustrated guide, both by the awesome people at GitHub.

Handling Updates from the default branch

While you're working away in your branch, it's quite possible that the upstream target branch may be updated. If this happens you should:

1. Stash any uncommitted changes you need to
2. git checkout vX_Y_Z
3. git pull upstream main
4. git rebase main myBranch
5. git push origin main - (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 pure evil, which is why we require 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 myBranch
2. Send a descriptive Pull Request on GitHub - making sure you have selected the correct branch in the GitHub UI!