When contributing to an GHE project the first thing to do is to fork the main repository and then clone it to your machine.

This is normally known as a triangular workflow.

Screen Shot 2016-02-01 at 6.48.37 AM

 

  1. Navigate to the GHE page for the project that you want to contribute to (for instance and fork it.
    • Click on the “fork button” in the top right corner of the repo’s page.
    • Click on your account in the modal which appears.
    • You’ll then be taken to your fork.
  2. In the right column of the page you’ll find the git clone URL. Make sure to select the SSH URL.
  3. Clone your fork.
    • git clone git@xxx:$USER/yyy.git && cd xxx
      

  4. Add the main repository as your upstream remote
    • git remote add upstream git@xxx:yyy.git
      

  5. Disable pushes to upstream, to minimise the risk for mistakes:
    • git remote set-url --push upstream no_push
      

  6. Make sure git pushes to your fork by default.
    • git config remote.pushdefault origin
      

  7. Make sure git only pushes the current branch.
    • git config --global push.default simple
      

  8. Tell git and GHE who you are.
    • git config --global user.name "Your Awesome Name"
      

    • git config --global user.email "${USER}@xxx.com"
      

  9. Optionally (although highly recommended); set your master branch’s remote to upstream. This way you don’t need to manage to master branches, your fork’s is quite useless anyways. Making your life over 9000 times easier.
    • git fetch upstream
      

    • git branch --set-upstream-to=upstream/master master
      

 

Suggested workflow

This is our suggested workflow for day-to-day work, after having setup your fork (origin) of the main repository (upstream).

  1. First, make sure to base your changes on latest master:
    • git checkout master && git pull upstream master
      

  2. Make a topic branch for your change
    • git checkout -b my-fix
      

    • Note: you must to do this or bad things will happen.
  3. Do the changes and commit them. Keep the commits small and atomic; for instance, don’t do code style changes in the same commit as something that fixes a bug, and don’t do refactors and behavior changes in the same commit.
  4. Push the changes to your fork:
    git push -u origin my-fix
    

  5. Open a pull request (PR) from your topic branch to master in the main repo. Either via;
    • hub pull-request -b xxx:master
      

      or

    • the GitHub web interface.
  6. Mention the relevant people or teams in the body of the pull request using the@username syntax (also works for teams, i.e. @the_org/team_name).
  7. It is OK to merge a PR once it has been reviewed and the reviewer has written a comment that clearly states that it is approved, for instance by writing “+2” or “Approved”.
  8. If merging a PR to upstream conflicts, merge master to your branch and update the PR:
    • git fetch upstream master && git merge upstream/master
      

  9. The person who created the PR is typically the one who is expected to merge it (and fix conflicts if necessary). Although an approved PR can be merged by anyone if needed.
  10. Once your topic branch has been merged into master go ahead and remove it in your own fork.
    • Either via the GHE pull request interface by clicking on “Delete Branch” or,
    • via the CLI: git branch -d my-fix && git push origin :my-fix