SSP Source Code Upgrade Process

# By convention, the 'origin' remote typically points to your fork in your Git hosting service,
# and upstream points to the canonical Apereo SSP repo in Github. E.g.:
#    $ git remote -vvv
#    origin	git@github.com:edu.edu/SSP.git (fetch)
#    origin	git@github.com:edu.edu/SSP.git (push)
#    upstream	git@github.com:Jasig/SSP.git (fetch)
#    upstream	git@github.com:Jasig/SSP.git (push)
# 
# Get the latest remote code
$ git fetch origin
$ git fetch upstream
 
# Make sure you're on your dev branch. The convention is <institution>-ssp-dev
$ git checkout edu-ssp-dev
 
# If that errors out, with an error like:
#    error: pathspec 'edu-ssp-dev' did not match any file(s) known to git.
# Then you probably need to create the branch and link it the remote copy that should already exist in 'origin':
$ git checkout -b edu-ssp-dev origin/edu-ssp-dev
 
# Capture local changes. This will help with two things:
#
#   1. Deciding whether to merge or reset-and-cherry-pick, and
#   2. Sanity checking the result of either approach
#
# This can be a bit complicated (http://stackoverflow.com/questions/1527234/finding-a-branch-point-with-git)
# but usually it's sufficient to get the diff against the current state of the upstream
# branch on which your dev branch is based:
#
#  $ git diff upstream/<most-recently-merged-branch>..HEAD
#   
 
# E.g. for a local dev branch based on rel-2-3-patches:
$ git diff upstream/rel-2-3-patches..HEAD > /my/upgrade/notes/pre-upgrade-local-diff
 
# Or, get a list of all the commits in your dev branch that aren't in the most
# recently merged upstream branch. Again, for a 2.3-based dev branch:
$ git rev-list upstream/rel-2-3-patches..HEAD
 
# Or:
$ git log upstream/rel-2-3-patches..HEAD
 
# It may also be useful to use a tool like Atlassian SourceTree to help visualize how your dev branch has diverged
# and inventory the patches to be preserved.
 
# If local changes are minimal, such that a merge is likely to create more problems
# than it solves because of unrelated conflicts in upstream code, it's often easiest
# to just reset your dev branch to point to the target upstream branch and cherry-pick
# local customizations into the result. E.g.:
#
# Create a branch to hold your place:
$ git checkout -b edu-ssp-dev-pre-upgrade
# Switch back to "main" dev branch
$ git checkout edu-ssp-dev
# Force dev branch to point at upgrade target. E.g. for a 2.4 upgrade:
$ git reset --hard origin/rel-2-4-patches
# Re-apply local changes via cherry-pick. E.g. for each commit in
# 'git rev-list upstream/rel-2-3-patches..HEAD' from above:
$ git cherry-pick <commit>
# If git reports conflicts on a cherry-pick command, you'll need to:
#  - Get the list of unstaged files. These are the conflicted files:
$ git status
#  - Open each conflicted file, correct the conflicts and
#    'git add' the corrected files (http://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging):
$ git add <corrected-file>
#  - Complete the cherry-pick once all conflicts are corrected. You should
#    be prompted to edit the commit message.
$ git cherry-pick --continue
 
# Or, if local changes are extensive, such that history is important and isolating each
# relevant commit for cherry-pick is not feasible, use a standard 'git merge'. Again
# assuming an upgrade to 2.4.x:
$ git merge origin/rel-2-4-patches
# Deal with conflicts in the same way as described above for cherry-picks:
#  - Get the list of unstaged files. These are the conflicted files:
$ git status
#  - Open each conflicted file, correct the conflicts and
#    'git add' the corrected files (http://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging):
$ git add <corrected-file>
#  - Commit the result once all conflicts are corrected
$ git commit