Git Workflow for Non-Committers

For non-developers (people without push access) the following workflow is strongly recommended. This guide is setup assuming you are making a change with the intent of getting it included in the main Jasig/uPortal GitHub repository. If you are using git to maintain a customized version of uPortal please see Git Workflow for Vendor Branching

Project Setup

See http://help.github.com/fork-a-repo/ for information on how to create a fork, clone it and add a reference to the https://github.com/Jasig/uPortal repository.

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.

On This Page

# retrieve the updates from the upstream repository
$ git fetch upstream -p

# switch to the master branch
$ git checkout master
 
# rebase your master branch upon the upstream master
# this rewrites history as if you had made your local changes upon 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

Never Commit to Master!

Or any other branch that exists in the https://github.com/Jasig/uPortal repository. If you do make a commit on a branch that is tracking a real uPortal branch and that commit is not accepted as part of a pull request you will be maintaining that customization for the rest of your fork's life. It is always better to not commit on project branches for a project that you do not have push access to and to use topic or vendor branches instead.

Making a Change

Use these instructions when making a change that you intend to be merged into the Jasig/uPortal repository.

Follow the steps in Keeping Up To Date

Create a Topic Branch

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

Make your changes

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

Repeat Steps 3 & 4 until the Topic work is complete
If during the work on the topic branch there is a change on master that you need to complete the work on the topic branch use the rebase command to replay your changes on the latest state of the master branch
```
# Fetch the latest changes from the GitHub repository
$ git fetch --all
# Rebase your topic branch commits on the latest changes from master
$ git rebase upstream/master
```

Push your Topic Branch

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

Follow http://help.github.com/send-pull-requests/ to make a pull request from your UP-XXXX topic branch to Jasig/uPortal

Once the pull request has been merged delete your topic branch

# Delete the local branch reference
$ git branch -d UP-XXXX
# Delete the remote branch reference
$ git push origin :UP-XXXX