RAS Git Workflow

When using Git and GitLab to develop and check-in changes to the RAS codebase, follow this process.

1) Create a new branch for your work

Create a new branch in your local git repository that you will use to perform the work. Open a git bash shell within the appropriate repo, then run the command:

git checkout -b branch_name

The 'branch_name' should be substituted with the JIRA number of the related ticket (e.g., RAS-1234).

This command will create a new branch with the given name and switch your view within git to that new branch. The branch you're currently working in will be displayed in the git bash shell in parentheses.

2) Make your changes on the branch

While in the branch, perform whatever work you need to do as normal. You can add new files to the repo with the command 'git add' and commit changes with 'git commit'. You can commit multiple times on the same branch, and the changes will remain local to your machine until you push them to GitLab in the next step.

If you are working on multiple tickets simultaneously, you can switch between branches with the command 'git checkout another_branch_name'. You will need to commit your outstanding changes in the current branch before switching; if you prefer not to do this, you can also use the 'git stash' command to temporarily save your changes and restore them later (see the documentation for git stash).

3) Push your branch to GitLab when it's ready to be merged

Once you've completed work on your branch and are ready to merge it, push it to the GitLab server with the command:

git push origin branch_name

This command will push your branch and all of its committed changes to the central GitLab server.

4) Create a Merge Request in GitLab

Log into GitLab and go to the project in which you're working. In the 'Push Activity' feed, you should see that your branch has been pushed to the server and is awaiting merging.

Click the 'Create Merge Request' link beneath the push event to begin this process.

On the New Merge Request page, you can optionally change the title of your merge or add a description, but the most important thing is to assign the merge to someone. RAS policy is that all changes must be reviewed by another developer before they can be merged, so select another team member to assign your merge to.

Once an assignee is selected, click the 'Submit Merge Request' button to create the merge request. The person assigned to the request will be notified, and they should review the request as soon as is feasible and either approve it for merging or request further changes. It's a good idea to keep tabs on the status of your merge request to ensure that it doesn't get forgotten or run into merge problems.

Once the reviewer has approved your merge request, GitLab will merge your branch into the

Reviewing a Merge Request

If you are assigned a merge request to review, you will receive an email notification from GitLab. You can also see the number of outstanding merge requests in the navigation bar at the left side of GitLab.

When viewing a merge request, you can review the contents of the branch and leave comments using the tabs at the bottom of the page:

• The 'Discussion' tab can be used to leave high-level comments that aren't specific to a particular file or change.
• The 'Commits' tab can be used to browse the commits that were made on this branch.
• The 'Changes' tab can be used to view individual changes and leave comments on a line-by-line basis.

Approving a merge request

If you are ready to approve a merge request, check the box for 'Remove source branch' on the main page of the request, then click the 'Accept Merge Request' button.

GitLab will merge the branch into the master branch and report on the results. Usually merges will succeed without any further action necessary, but if merge conflicts are reported they'll need to be manually resolved. (Details TBD)

Rejecting a merge request

If it's determined that a branch pushed to GitLab should not be merged, or needs further work before it can be merged, the reviewer can close the merge request without merging the branch by using the 'Close merge request' button (preferably while also leaving a comment explaining why).

The submitter can then make further changes on their branch, if necessary, and push the new commits to GitLab in order to open a revised merge request.

Cleaning up Git branches

Since a new branch is created for each JIRA ticket, you may end up with a large number of branches in your local git repos. Selecting the 'Remove source branch' option when merging in GitLab removes those branches from the server, but not from your local machine.

Once your branch is merged into master, you probably don't need it anymore. Leaving these branches as-is shouldn't hurt anything, but if you'd like to clean them up, you can use the command 'git branch' to print all of the branches that exist in the current repo, and 'git branch -d branch_name' to delete a branch.

Updating ras-kuali repos

When we want to upgrade to a new Kuali release, we need to update our ras-kuali repos to the latest Kuali revision and then select the appropriate release tags for the new build. Run the following commands in each of the ras-kuali repos:

Create a new branch off of 'master' for merging in the updates

Replace 'kc-1606' with the version of the new release; this will be the branch name used in the merge.

git checkout master
git checkout -b kc-1606

Add the Kuali github as a remote source, if necessary

Run the git remote command to view the remote repositories linked to this repo.

git remote -v

If the output of this command shows the Kuali github addresses as a remote repo in addition to the GitLab addresses, you can skip to the 'git fetch' step below. Otherwise, you'll need to add the github repo as a remote source, replacing the URL here with the correct github address for the matching repo:

git remote add github https://github.com/kuali/kc-s2sgen

Fetch the new commits from Github

Once the github address has been set up as a remote repo, you are ready to fetch the changes from github to your local repository:

git fetch github

This will pull all new commits, branches, and tags that have been added to the github repo since your last fetch into your local repo.

Merge the Github changes into the local branch

Run the merge command to merge the contents of the Github 'master' branch into the current local branch.

git merge github/master

Push the new changes to GitLab

Run the following commands to push the new changes and tags to the GitLab server. New tags are not pushed by default, so the second command is necessary to sync those to the server.

git push origin kc-1606
git push origin --tags

Merge the changes within GitLab

Create a merge request on GitLab as described above, and merge the new branch into the master branch. The repo has now been synced with the Kuali Github repo, and the changes can be pulled down to your local repo using the 'git pull' command.

The repo will be at the latest commit by default, so you may need to checkout a specific release tag in order to build a specific version of the project.