Saturday, March 12, 2011

patching github projects

Wow, adding changes to projects on github is surprisingly easy, once you figure out the steps. I made a patch for vim-space earlier today, after I found an error in a comment that cost me an hour yesterday.

I nearly got the github flow correct on the first pass. Here's what I did:

  1. fork the project (via UI on github)
  2. clone locally
    git clone
  3. make change to plugin.vim in my working directory, test:
    vim plugin.vim ...
  4. create an issue for the original project (via UI on github)
  5. commit change locally:
    git add plugin.vim
    git commit plugin.vim -m "[issue 7] ..."
  6. push change to my cloned repo on github:
    git push origin master
  7. create the patch file:
    git format-patch HEAD^..HEAD
  8. upload the patch file to the issue. Nope, can't upload files to the issue tracker at github.
  9. create pull request:
    git request-pull HEAD^ origin HEAD
    The following changes since commit 9640d4d1ee980e352abd96e2c0ef13372d1c14cd:
      Merge remote branch 'remotes/origin/master' (2010-04-13 16:22:27 +0200)
    are available in the git repository at: master
    Andrew Grangaard (1):
          [issue 8] correct loaded_space to space_loaded in plugin
     plugin/space.vim |    4 ++--
     1 files changed, 2 insertions(+), 2 deletions(-)
  10. Copy and paste this pull request into issue 7.

This was close to the correct flow. While the issue tracker on github doesn't allow uploaded files in the comments, it does track pull requests. So the flow should look like:

Correct Flow

  1. Clone Repo (github UI)
  2. clone locally:
    git clone
  3. Make Changes, test
    vim plugin.vim ...
  4. commit locally:
    git add plugin.vim
    git commit -m "loaded_space fix"
  5. push to github:
    git push origin master
  6. issue pull request(github UI)
  7. done. bask in the warm glow of improving an open source project.

The issue pull request stage will create a tracking issue. Slickness. The Clone and Pull Request are handled in the github UI. Check the Pull Requests as Github UI documentation for pretty pictures.

Proper form would be to create a topic branch in the cloned repository, this becomes more useful if you plan to make any further changes or modifications to the project. Make the upstream girl's job as easy as possible to enhance the likelihood of your changes being accepted.

No comments: