Git Workflow for Committers

Owned by Eric Dalquist
Last updated: Mar 01, 2016 by Benito GonzalezVersion comment

For developers (people with push access) the following workflow is strongly recommended.

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.

On This Page

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 local branch onto the the incoming changes
# (this rewrites history as if you had done your work on 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

Making a Minor Change

Use these instructions when making a change that only requires one commit.

  1. Follow the steps in Keeping Up To Date 
  2. Make your changes

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

  4. Push your Changes 

    # Push changes to your fork first, when this completes you can go to GitHub and verify the commits look as you expect
$ git push origin
 
# Push changes to the Jasig repository
$ git push upstream

Making a Major Change

Use these instructions when making a change that requires multiple commits or review by others

  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. Push your Topic Branch 

     # Push the branch to your fork for others to review
$ git push origin UP-XXXX
  6. Repeat from Step 3 until the Topic work is complete
  7. Follow the steps in Keeping Up To Date

  8. Merge your topic branch into master 

    # Switch to the master branch
$ git checkout master
 
# Merge the topic branch into master
$ git merge UP-XXXX
 
# Resolve merge conflicts if any are reported
$ git mergetool -y

  9. Push your Changes 

    # Push changes to your fork first, when this completes you can go to GitHub and verify the commits look as you expect
$ git push origin
# Push changes to the Jasig repository
$ git push upstream

Updating Patches Branches

Use these instructions when making a change that is required on multiple branches. For example fixing a bug in 4.1.0 (master) that also exists in 4.0.6 (rel-4-0-patches)

  1. Follow either the Making a Minor Change or Making a Major Change steps above

  2. Record the commit ID(s) involved in the change. A tool such as gitk or the commit log on GitHub can be used as well.

    # View the commit log for the current branch
$ git log

  3. Checkout the branch to apply the change to

    # Switch to the 4.0-patches branch
$ git checkout rel-4-0-patches
  4. Follow the steps in Keeping Up To Date for the target branch

  5. Cherry-Pick the commit(s) for the change into the branch

    # Switch to the 4.0-patches branch
$ git cherry-pick ba5eba11 cab005e 0ddba11
 
# Resolve merge conflicts if any are reported
$ git mergetool -y

  6. Push your Changes 

    # Push changes to your fork first, when this completes you can go to GitHub and verify the commits look as you expect
$ git push origin
# Push changes to the Jasig repository
$ git push upstream

Merging Pull Requests

When a pull request from a non-committer comes in the following review steps need to be taken before and after the merge

 

Pre-Merge Steps

  1. Verify that all commits in the pull request reference the Jira Issue ID that the pull is addressing
  2. Do a code review of the changes 

Merge Steps

  1. If the Pre-Merge steps all look good you can use the green Merge Pull Requestbutton.
    1. Once the request has been merged it is your responsibility to pull down the changes locally and verify they actually work.

    2. If there is a problem with the merge do a local revert and then push that to GitHub

      # Revert the merge commit
$ git revert -m 1 COMMIT_ID_OF_MERGE_COMMIT
# Push changes to the Jasig repository
$ git push upstream
  2. If there are problems with the commit messages either close the pull and request the user to rework the commits or do a local merge and use rebase -i to rewrite the commit messages. These steps are available from the info icon on the left edge of the Merge bar on the pull request page

    1. Check out a new branch to test the changes — run this from your project directory

      $ git checkout -b user-name-UP-XXXX master

    2. Bring in user-name's changes and test

      $ git pull git://github.com/user-name/uPortal.git UP-XXXX
    3. Interactive Rebase to rewrite the commit messages by following the steps here: https://help.github.com/articles/interactive-rebase

    4. Merge the changes and update the server

      $ git checkout master
$ git merge user-name-UP-XXXX
$ git push origin master

Post-Merge Steps

  1. Update the JIRA issue to resolved.  Make sure the Fix Version is correct.

Releasing artifacts

To release artifacts perform the following steps.  You will also need to setup your account with Sonatype first.  See Sonatype documentation.

# Insure you have no changed files or files that are not being tracked
$ git status
# git stash if need be.  If you have files not being tracked, those should be added first to have the stash
#           remove from from the file system.
$ git checkout master
$ git pull upstream master
 
# Optional, check for updated dependencies
mvn versions:display-dependency-updates

# Verify project builds properly
$ mvn clean install license:check notice:check javadoc:javadoc
# fix any issues
# javadoc:  Building with Java 8 often reports javadoc issues that did not occur when building with Java 7.
#           It's strongly discouraged but for Java 8 javadocs issues, you can consider whether it is reasonable
#           to add '-Xdoclint:none' as specified at the following to not run Xdoclint
#           http://stackoverflow.com/questions/15886209/maven-is-not-working-in-java-8-when-javadoc-tags-are-incomplete
#           Update: This did not work for me.  The javadoc seemed to run twice. The first time OK and the second with errors
#           despite mvn help:effective-pom showing that every merged instance had -Xdoclint:none set.
#
#           Here is an approach that sets the parameter based on a profile activated when using Java 8+:
#                    <profiles>
#                        <profile>
#                            <id>disable-java8-doclint</id>
#                            <activation>
#                                <jdk>[1.8,)</jdk>
#                            </activation>
#                            <properties>
#                                <additionalparam>-Xdoclint:none</additionalparam>
#                            </properties>
#                        </profile>
#                    </profiles>
#                
# license:  If you get many error about license headers, the headers may have changed (this happened when Jasig
#           became Apereo). Execute the command 'mvn license:format' to replace existing license headers with
#           new license headers and commit the result.  To update notices, run 'mvn notice:generate'.
# if need be, do git commit -m "NOJIRA pre-release prep"

$ mvn release:clean
$ mvn release:prepare

# Temporary: Verify maven release steps are committed.  Look for commits like
# [maven-release-plugin] prepare for next development iteration
# [maven-release-plugin] prepare release jasig-widget-portlets-2.1.4
#
# If not present:
# - commit the change seen in https://github.com/Jasig/JasigWidgetPortlets/commit/f2597e442be90d350382c69ec5aee62b49b620d5
# - If the tag was pushed to upstream, you'll have to delete the local tag using the command 'git tag -d <tagname>' 
#   and the remote tag using the command 'git push upstream :refs/tags/<tagname>'.  Then re-run mvn release:perform.
git log

# release:perform uploads artifacts to Sonatype
$ mvn release:perform

# In Sonatype Staging Repository:
# - Select repository and close it. Wait a bit and refresh.
# - Validate artifacts on Sonatype and release artifacts.

# Release is complete.  
# If you have multiple repositories and origin is not the Jasig repository, 
# you need to push commits to upstream to push the commits and the tag.
git push upstream master
git push upstream <tagname>
If you have a single repository, or your origin repository is the Jasig repository, 
release:prepare and release:perform commits will be pushed to github automatically.

Additionally, it is helpful to do the following:

JIRA

  1. Insure all issues referenced in the git commits since the last release are marked as resolved with the correct release version (especially if you did a major or minor release and not a patch release).
  2. Request the JIRA project owner to mark the version # you released the portlet as released and create a new patch version #

Wiki Documentation

  1. As best you reasonably can, review the uportal or portlet Wiki document and update it as appropriate, especially any configuration additions/changes.  Ideally this was already done by the individual committers.

Â