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
 
# Create a branch to hold your place:
$ git checkout -b edu-ssp-dev-pre-upgrade
 
# Push it to your hosted repo:
$ git push origin edu-ssp-dev-pre-upgrade
 
# Switch back to your actual dev branch:
$ git checkout 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.
#
# Start by forcing the local 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
 
# See below for more information on typical merge conflicts.
 
# Try building SSP:
$ mvn -Dmaven.test.skip=true clean install
 
# If there are problems, the errors will usually come from the Java compiler and will list the problematic
# source files. For each such problematic file, open it for edit, fix the problem, and 'git add' the change:
$ git add <fixed-file>
# Repeat the fix/add/build process until the build completes successfully. Then commit the change.
# You should be prompted to supply a commit message:
$ git commit
 
# Sanity check that the differences relative to the upgrade target reflect the local customizations
# you decided should be preserved. Again for a 2.4.x upgrade:
$ git diff origin/rel-2-4-patches HEAD
 
# If anything seems to be missing either fix it right away or take a note to address it once
# you get to a more stable point in the overall upgrade.
 
# At this point you'll probably want to back up your work to your hosted repo.
# Push your dev branch to a temporary remote branch:
$ git push origin edu-ssp-dev:edu-ssp-dev-upgrade
 
# Now switch to the SSP-Platform source code upgrade process described below.
# Once that is complete and tested, you'll want to push your SSP dev branch
# to your hosted repo using its canonical name.
#
# If you used the 'reset' approach above, you'll need to specify the '-f' argument:
$ git push -f origin edu-ssp-dev
# Else if you used the 'merge' approach, leave the '-f' off:
$ git push origin edu-ssp-dev
 
# You may want to leave the placeholder 'edu-ssp-dev-pre-upgrade' branch as a
# reference point until the upgrade is complete. Once it's outlived its usefulness,
# you can delete it with:
$ git push origin :edu-ssp-dev-pre-upgrade