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
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.
# 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