Child pages
  • Git Workflow for Non-Committers
Skip to end of metadata
Go to start of metadata

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.

  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. Repeat Steps 3 & 4 until the Topic work is complete
  6. 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
  7. Push your Topic Branch 

    # Push the branch to your fork for others to review
    $ git push origin UP-XXXX
  8. Follow http://help.github.com/send-pull-requests/ to make a pull request from your UP-XXXX topic branch to Jasig/uPortal
  9. 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