Github workflow

This document will be used to keep notes on how to do development for the Grappa Github repository.

Clone the code

Become a collaborator on the Github project. Follow Github's instructions for cloning to your own machine.

Develop on a new branch

If you're working on a new feature, make a new branch and push to it.

Here's how it goes:

# create a new feature branch named foo
> git checkout -b feature-foo
# set up the branch to track a new branch of the same name on github
> git push -u origin feature-foo
# make some changes (e.g.)
> echo "adding stuff" >> README.md
# commit often
> git add README.md
> git commit -m "Add some stuff to readme."
# push your intermediate work on this branch to github
# (allows others to see it and 'saves' it in case, e.g., your laptop is stolen)
> git push

Checkout someone else's feature branch (or your own on a different local repo)

> git fetch origin
> git checkout --track origin/feature-foo

Pull Requests == Code Reviews

Usually on Github you see pull requests in the context of people who are not involved in the project getting their work included in the main repo. However, Github supports doing pull requests on branches as well (in fact, according to Scott Chacon this is what Github's developers themselves do).

Submitting new pull request

• Make sure the shared feature branch on Github is up to date (git push from feature branch)
• Go to Grappa on Github.
• Click on the "Pull Request" button at the top.
• Choose the feature branch in the right side dropdown, write description of new feature, and submit.

Submitting new pull request based on an existing Issue

• In Github, Pull Requests are Issues, but Issues are not in and of themselves Pull Requests. If you set out to solve an issue in a new branch, and want to submit a pull request to solve it, you can reference the issue in your pull request, but the issue still hangs around.
• To directly associate a new pull request with an existing issue, there is not currently support in the Github UI, but the API supports it, and the command-line Github tool hub uses it.
• If, for example you have a branch new-feature (the "head" branch) that fixes Issue #36, and you would like to merge into master (the "base" branch), the command is:

  hub pull-request -b uwsampa:master -h uwsampa:new-feature https://github.com/uwsampa/grappa/issues/36

Comments, feedback, fixes

• Others can make overall comments in the pull request Discussion thread ("Discussion" tab)
• Line-by-line comments can be made on commits or diffs, just go to the respective tab.
• Fixes can be made by adding more commits to the branch. They should automatically get added to the pull request.

Merging when complete

• If you don't mind the string of commits showing up in master as is, then in Github you can just press the "Merge pull request" button at the bottom of the pull request.
  • If automatic merge isn't possible, Github will warn you, and you'll have to manually (in a local repo) do the merge. The pull request should have instructions for how to do this (but it may be pretty involved).
• If you'd rather clean up the commits first, you have two ways to do this (not for the faint of heart):
  • Interactive rebase and merge
    • If you're brave enough to attempt interactive rebasing, this can be a nice way to clean up a branch into reasonably sensible commits, and get rid of intermediate merge commits that have happened in the process of staying up-to-date with master.
    • How-to:

      # Save original branch for posterity (and in case you screw the next steps up):
      > git branch feature-base-orig
      # Do interactive rebase of the branch (if you don't know how, probably don't try this)
      > git rebase --interactive
      # Force-push **just that branch** to Github
      # *Warning*: this will replace the original commits on Github, others who have 
      # checked out this branch should delete their local branch and re-checkout
      > git push --force origin feature-foo`
      # Github should now show the newly rebased commits rather than what was there
      # before (don't worry, you can still see comments on the old diffs)
      # From Github, you should be able to do a fast-forward merge of the pull request.

  • Squashed merge (not recommended):
    • Not sure if this resolves the pull request automatically. Creates a new commit on the target branch with the full diff of all the commits in the merged branch. Doesn't give credit to original committer.
    • How-to (should look something like this) Assuming branch to be merged is named 'feature-foo'. In local repo:

    > git checkout master
    > git merge --squash feature-foo
    # (enter new commit message for all the changes)
    # push changes back up to Github master
    > git push