github flow manifesto

manifesto.md

These ideas based on GitHub Flow and are heavily influenced by Jenny Bryan and Hadley Wickham, through their R package {usethis}.

Remotes

The term upstream refers to a remote that is the "canonical" repository for a project.

The term origin refers to a remote that is a fork of an upstream remote.

If you are one of the maintainers for a repository, you can push to the upstream remote.

Default branch

This is the branch in the upstream repository against which pull requests are normally made.

In some cases the default branch is master, in others it might be something like 1.4.x. This will depend entirely on the upstream repository.

Pull Requests

For the purpose of illustration, we assume the default branch is master.

Scenario: contributor

1. Make sure that your copy of the master branch is synchronized with the upstream branch.

   git checkout master
   git pull upstream master
   

2. Check out a new branch from master to contain your proposed changes. Here, it will be called new-feature, but you will want to call it something else:

   git checkout -b new-feature
   

3. Make some changes in the your new branch. Save; run local tests, if you have them. Commit them to your local branch. Then push your branch. If you have access to upstream, use it. If not, use origin

   git push -u upstream new-feature
   

4. Go to the GitHub page for the upstream repository. Open your pull resuest against a branch (probably the default branch). If you are still working on things, open the pull request as "Draft".

5. Continue working, saving, testing, and committing to your local branch. Every so often:

   git pull upstream new-feature
   git push upstream new-feature
   

6. When you are ready for your work to be merged or reviewed, go to the GitHub page for the PR, remove the "draft" status, and ask for a reviewer.

At any point in your process, you may have to incorporate others work into your new-feature branch.

• Another contributor or reviewer makes changes to your branch:

  1. Pull the remote branch into your local branch:

     git pull upstream new-feature
     

  2. You may have to solve a merge conflict. May the Force be with you. When you have solved the conflict (including testing), push the result to your remote branch:

     git push upstream new-feature
     

• Since you started your work in the PR, changes have been made in the upstream default branch. You should incorporate these changes into your work so that you can be confident that your PR will work as everyone expects when merged upstream.

  1. Pull the upstream default branch into your local branch:

     git pull upstream master
     

  2. You may have to solve a merge conflict. May the odds be ever in your favor. When you have solved the conflict (including testing), push the result to your remote branch:

     git push upstream new-feature
     

When your PR has been accepted, bring your master branch up-to-date, and delete your feature branch:

git checkout master
git pull upstream master
git branch -d new-feature

Scenario: maintainer

There may be times when looking at a PR in the GitHub client is not sufficient. You want to work with the code yourself, and possibly modify it.

1. Fetch the new-feature branch from the upstream remote. Be sure to fetch the branch, not pull it:

   git fetch upstream new-feature
   

2. Switch to the new-feature branch:

   git checkout new-feature    
   

3. Do your thing. Save. Test. Commit. Pull, then push your changes:

   git pull upstream new-feature
   git push upstream new-feature
   

   If you have a merge conflict, see above.

When the PR has been reviewed and everyone is happy, using the GitHub web-page:

1. merge it (I like to use "Squash and Merge")
2. delete the remote branch

You may also want to delete your local copy, see above.