Skip to end of metadata
Go to start of metadata

1. Workflow / Policy

All development work is done on a personal fork of the original Kuali Rice GitHub repository.  Pull request are used to contribute the development work back into the Kuali Rice GitHub repository.  During the pull request a code review is done.

Gliffy Zoom Zoom Simple Git Workflow for Rice

Warning

Icon

You are changing commit history whenever you are working with commands that include rebase (i.e. syncing your code and squashing the change log).  This is OK as long as only non-published commits are affected. Never rebase anything that has been published to the Kuali Rice repository!

1.1 Create GitHub Account

If you don't have a GitHub account sign up for one.  You may use your personal GitHub account or create one specific for Kuali work. It's up to you.  A free account is sufficient.

1.2 Install Git

Download git and install it locally on your computer.  You may choose to install Git through a package manager such as homebrew or from development tools such as xcode. Configure your username and email address with git.  This information will be part of your commits to identify who had done the commit.  Username can be anything but usually the real name, the GitHub user name, or an alias is used.  The email address must match with one of the email addresses on your GitHub account.  Use the following statements to configure these globally: 

git config --global user.name "John Doe"
git config --global user.email johndoe@example.com

Follow these GitHub instructions if you are worried about privacy and would like to keep your email address private.  Make sure to apply the changes on both, GitHub and your local git installation.

1.2.1 Changing Default Git Editor

The command line git client is using a text editor for several tasks (i.e. commit message editing and squashing commits interactively).  By default the Vim editor is used if you are unfamiliar with this editor you either need to learn its weird commands or change the default editor to one of your choice.

git config --global core.editor notepad.exe

Replace notepad.exe with your preferred editor (absolute path can be specified).

FYI: Saving the file applies the command.  Exiting the file without saving will abort the command.

1.3 Fork Kuali Rice GitHub

Navigate to the Kuali Rice repository on GitHub (https://github.com/kuali/rice) and click the Fork button in the top-right corner of the page.

1.4 Working with Personal Fork

1.4.1 Create Local Clone

To create a local working copy on your computer use git to clone your personal forked Kuali Rice repository.  Do not clone the Kuali Rice repository directly.  You can copy the clone URL from right sidebar of your forked Rice repository on GitHub. It should be similar to this URL where YOUR-USERNAME represents your GitHub user name.

https://github.com/YOUR-USERNAME/rice

Git client specific instructions:

 Command Line Git Client

Replace YOUR-USERNAME with your GitHub user name.

git clone https://github.com/YOUR-USERNAME/rice.git

To simplify git usage with this repository we add the Kuali Rice repository url as the upstream repository

git remote add upstream https://github.com/kuali/rice.git
 IntelliJ Integrated Git Client

ToDo

 Eclipse Integrated Git Client

ToDo

1.4.2 Create New Branch

Git client specific instructions:

It is recommended that the changes for each JIRA is done in a separate branch.  Using the JIRA number (eg. KULRICE-1234) is a good naming convention.

 Command Line Git Client

If you need to make a change on a different branch besides master (such as rice-2.5), checkout the rice-2.5 branch before running the commands below

git checkout rice-2.5

First the new "KULRICE-1234" branch is created and then the working environment is switched to the newly created branch:

git branch KULRICE-1234
git checkout KULRICE-1234

As a shortcut this one liner does the same as the two commands above:

git checkout -b KULRICE-1234
 IntelliJ Integrated Git Client

There are 3 Ways to do this in IntelliJ.

First :

VCS Menu -> Branches -> New Branch-> Enter Name of Branch -> Click OK.
 
This will do create and checkout

Or Second:

On the status bar at the bottom right hand side the current Git branch is shown. 
 
Click on that area and a menu pops up. Choose New Branch-> Enter Name of Branch -> Click OK.
 
This also will do a create and checkout.

Or Third :

Right Click anywhere in a loaded project, and a menu pops up.
 
Choose Git -> Repository -> Branches -> New Branch-> Enter Name of Branch -> Click OK.
 
This also will do a create and checkout.
 Eclipse Integrated Git Client

ToDo

1.4.3 Committing

Committing causes your changes to be applied to the local repository.  While this allows you to switch your workspace to another feature/JIRA the code is still on your computer. Consider also pushing the committed changes to your personal Github repository for backup reason.

Git client specific instructions:

 Command Line Git Client

Before committing it's always good to check the current state of the local project.  This command will show which changes are to be committed (aka the staging area):

git status 

To add changes to the staging area:

git add myFile   // stages a specific file
git add -A       // stages all files
git add .        // stages new and modified files (does not include deleted files)
git add -u       // stages modified and deleted files (does not include new files)
git rm myFile    // stages a specific file that was deleted

To remove changes from the staging area:

git reset myFile // unstages a specific file
git reset        // unstages everything

Finally to commit the changes the following command will cause a commit editor (by default Vim) to be opened.  Here you enter the commit notes.

git commit

Hint: Exiting out of the editor without saving causes the commit to be canceled.  The commit message can also be specified on the command line.  No editor is then displayed.

git commit -m "KULRICE-1234 This is the commit Message"
 IntelliJ Integrated Git Client

To check the the current state of the local project just click and take a look at the Changes tool window at the bottom. This window will show what is currently set to be committed as well as unversioned files that can be added.

To add changes to the staging area. This can be done several ways inside the Changes Tool Window

1. Drag the file from the unversioned file list to the Default list.
2. Or you can right click on the unversioned file and click on Add to VCS. This will add the the file to the Default list.
3. Or just change the contents of a file, and that will also add that file to the Default list.

To Remove changes from the Staging area

You can right click on a file or file(s) in the changes tool window under Default and click on Revert

Commiting All Files to the Local repository can also be done several ways

1. In the Changes Tool Window right click on the Default list -> Commit Changes
2. or Also In the Changes Tool Window, click on the  vcs upload button.
3. or Click on the top level directory in a loaded project and then click on the VCS Menu -> Git -> Commit Directory

Once you are looking at the Committing Changes Dialog

you can enter your commit message and then choose the commit button at the bottom to choose 'commit' or 'commit and push'

 

 Eclipse Integrated Git Client

ToDo

1.4.4 Reverting

To revert changes that haven't committed yet simply remove them from the staging area (if necessary) and perform a checkout.

Git client specific instructions:

 Command Line Git Client
git reset myFile     // remove from staging area
git checkout myFile  // revert changes by checking out the original
 IntelliJ Integrated Git Client
1) You can right click on a file or file(s) in the changes tool window under Default and click on Git -> Revert
2) Or, you can right click on a file or file(s) in the project window and then click on Git -> Revert
3) Or, you can right click on a file or file(s) in the project window and then go to the VCS menu -> Git -> Revert
 
 Eclipse Integrated Git Client

ToDo

1.4.5 Squashing Change Log

Before creating a pull request you should combine your commits into one (or a very few historically useful) commits.  To do so use the interactive git rebase command to combine the commits and update their message.

Git client specific instructions:

 Command Line Git Client

Start git's interactive rebase editor.  The HEAD~2 allows you to squash the last two commits.  A different number than 2 can be specified in order to work with more commits.

git rebase -i HEAD~2

To combine commits keep the pick command on the first commit and change the commands of all following commits that should be combined with the first one to squash.  After rebasing a new text editor will ask to to update the commit message.

To view only your local changes use the following command:

git log origin..
 IntelliJ Integrated Git Client

ToDo

 Eclipse Integrated Git Client

ToDo

1.4.6 Syncing with Kuali Rice Repository

Before creating a pull request syncing your branch with the Kuali Rice repository is required.  This avoids merge conflicts and allows you to test your changes with the latest code.

Pull-rebase is used for our synching process.  

Git client specific instructions:

 Command Line Git Client
git pull --rebase upstream master

Or if you are working on a different branch such as rice-2.5

git pull --rebase upstream rice-2.5
 IntelliJ Integrated Git Client

ToDo

 Eclipse Integrated Git Client

ToDo

1.4.7 Pushing Changes to your Private GitHub Repository

Pushing changes to your private GitHub repository has two functions.  It backs up your work and allows your work to be shared easily with other team members.

 Command Line Git Client

Pushing the "KULRICE-1234" branch to your private GitHub Rice repository

git push origin KULRICE-1234

If you squashed the change log after having pushed the changes previously then the --force flag needs to specified otherwise the push will fail.

git push --force origin KULRICE-1234
 IntelliJ Integrated Git Client

ToDo

 Eclipse Integrated Git Client

ToDo

1.5 Creating a Pull Request

Pull request are best done from GitHub itself.  After syncing, squashing and pushing your changes to your private GitHub rice repository go to the branch on GitHub.com and start creating the pull request by pressing the green button.

 

See GitHubs Help pages for step-by-step instructions.

1.6 Code Reviewing a Pull Request

1.6.1 Rice Developers

For new pull requests, CI will start a job to verify that all unit tests passe.  The CI job will comment on the pull request whether or not the unit test has failed.

After the unit test passes one (preferably two) rice developer will pickup the code review and comment if the pull request is acceptable or not.  Note that reviews of pull request will not be assigned and thus need to be picked up by developers as they occur.

Specific items to check:

  • Use KIS to check that CLA is on file for contributor
  • Check that 3rd party licenses are acceptable
  • Pull request made against correct branch (check JIRA fix version)
  • Commits are prefixed with JIRA id (e.g. KULRICE-1234)
  • Code and comment style are followed
  • If applicable tests are supplied
  • Project build and unit tests are passing
1.6.2 Contributors

Pull request from non white listed (Rice) developers are considered contributor pull request.  For these CI will not automatically compile the pull request in order to avoid any potential malicious acts. Instead the CI job will comment on the pull request that the code needs to be reviewed and that the unit testing still has to occur.  Only after the reviewer is confident that the code is safe to compile should the CI job to verify the unit tests be started.  To do so add ok to test as a comment to the pull request.  At this point the review continues as described in 1.6.1.

When either the integration or functional test fail after a merger these need to be fixed.  For contributions the rice team may choose between fixing the issues themselves or reverting the merger and have the contributor fix the issues.

1.7 Merging a Pull Request

Merging is to be done by a different person than the developer that requested the pull request.  This is to ensure that at least two pair of eyes have seen the contributed code.  Merging should only done if the pull request is satisfactory according to the code review and the unit tests passed.

  • No labels