/
Git Workflow for Committers

Git Workflow for Committers

Mar 01, 2016

Keeping Up To Date

These instructions can be applied to any branch by replacing master with the branch you're interested in keeping up to date, rel-3-2-patches for example.

# retrieve the updates from the upstream repository $ git fetch upstream -p # switch to the master branch $ git checkout master # rebase your local branch onto the the incoming changes # (this rewrites history as if you had done your work on the latest and greatest) # # WARNING: DO NOT DO THIS UNLESS YOU UNDERSTAND WHAT IT MEANS TO REBASE # In particular, if you've shared your local master branch with others, you *might* # want to avoid rebasing so as to avoid the inconvenience of changes to a shared history. # In this as in many things, effective communication and shared expectations are essential. # Littering your history with merge commits has a noise cost too. It's probably worth it to rebase. # # If you can't use rebase, instead do git merge upstream/master. $ git rebase upstream/master # now you're ready to update your fork $ git push origin master

Making a Minor Change

Use these instructions when making a change that only requires one commit.

  1. Follow the steps in Keeping Up To Date 

  2. Make your changes

  3. Commit your changes

    # View the list of your changes $ git status # If all new/modified/deleted files should be committed $ git commit -a # If only some new/modified/deleted files should be committed $ git add each new/changed file $ git rm each deleted file $ git commit

  4. Push your Changes 

    # Push changes to your fork first, when this completes you can go to GitHub and verify the commits look as you expect $ git push origin # Push changes to the Jasig repository $ git push upstream

Making a Major Change

Use these instructions when making a change that requires multiple commits or review by others

  1. Follow the steps in Keeping Up To Date 

  2. Create a Topic Branch 

    # Create a topic branch, use the Jira Issue ID for ease of tracking $ git checkout -b UP-XXXX

  3. Make your changes

  4. Commit your changes 

    # View the list of your changes $ git status # If all new/modified/deleted files should be committed $ git commit -a # If only some new/modified/deleted files should be committed $ git add each new/changed file $ git rm each deleted file $ git commit

  5. Push your Topic Branch 

     # Push the branch to your fork for others to review $ git push origin UP-XXXX

  6. Repeat from Step 3 until the Topic work is complete

  7. Follow the steps in Keeping Up To Date

  8. Merge your topic branch into master 

    # Switch to the master branch $ git checkout master # Merge the topic branch into master $ git merge UP-XXXX # Resolve merge conflicts if any are reported $ git mergetool -y

  9. Push your Changes 

    # Push changes to your fork first, when this completes you can go to GitHub and verify the commits look as you expect $ git push origin # Push changes to the Jasig repository $ git push upstream

Updating Patches Branches

Use these instructions when making a change that is required on multiple branches. For example fixing a bug in 4.1.0 (master) that also exists in 4.0.6 (rel-4-0-patches)

  1. Follow either the Making a Minor Change or Making a Major Change steps above

  2. Record the commit ID(s) involved in the change. A tool such as gitk or the commit log on GitHub can be used as well.

    # View the commit log for the current branch $ git log

  3. Checkout the branch to apply the change to

    # Switch to the 4.0-patches branch $ git checkout rel-4-0-patches

  4. Follow the steps in Keeping Up To Date for the target branch

  5. Cherry-Pick the commit(s) for the change into the branch

    # Switch to the 4.0-patches branch $ git cherry-pick ba5eba11 cab005e 0ddba11   # Resolve merge conflicts if any are reported $ git mergetool -y

  6. Push your Changes 

    # Push changes to your fork first, when this completes you can go to GitHub and verify the commits look as you expect $ git push origin # Push changes to the Jasig repository $ git push upstream

Merging Pull Requests

When a pull request from a non-committer comes in the following review steps need to be taken before and after the merge

 

Pre-Merge Steps

  1. Verify that all commits in the pull request reference the Jira Issue ID that the pull is addressing

  2. Do a code review of the changes 

Merge Steps

  1. If the Pre-Merge steps all look good you can use the green Merge Pull Requestbutton.

    1. Once the request has been merged it is your responsibility to pull down the changes locally and verify they actually work.

    2. If there is a problem with the merge do a local revert and then push that to GitHub

      # Revert the merge commit $ git revert -m 1 COMMIT_ID_OF_MERGE_COMMIT # Push changes to the Jasig repository $ git push upstream

  2. If there are problems with the commit messages either close the pull and request the user to rework the commits or do a local merge and use rebase -i to rewrite the commit messages. These steps are available from the info icon on the left edge of the Merge bar on the pull request page

    1. Check out a new branch to test the changes — run this from your project directory

      $ git checkout -b user-name-UP-XXXX master

    2. Bring in user-name's changes and test

      $ git pull git://github.com/user-name/uPortal.git UP-XXXX

    3. Interactive Rebase to rewrite the commit messages by following the steps here: https://help.github.com/articles/interactive-rebase

    4. Merge the changes and update the server

      $ git checkout master $ git merge user-name-UP-XXXX $ git push origin master

Post-Merge Steps

  1. Update the JIRA issue to resolved.  Make sure the Fix Version is correct.