Applying Kuali Updates to RAS

Owned by Chris Smith
Last updated: Mar 21, 2019

Update build branches

  • Build order for the projects is at the top of the build instructions here: https://github.com/KualiCo/kc/blob/master/README.md
    • The typical order is schemaspy > kc-rice > kc-api > kc-s2sgen
  • For each project in order, do the following:
    • Open Git Bash in the project folder
    • git remote -v
    • git checkout master
    • git fetch github
      • This will pull down all new tags from the KualiCo repo
    • Check the KC master POM file to find the current required version number for each project (it's not always the latest version needed): https://github.com/KualiCo/kc/blob/master/pom.xml
    • git checkout <tag for project version that matches the KC POM file>
      • e.g. git checkout coeus-s2sgen-1901.0001
    • Add the tag to the RAS Current Build Branches wiki page: RAS Current Build Branches
    • Build the project:
      • mvn clean install -Dgrm.off=true
    • Push the tags up to the Tufts GitLab repo:
      • git push --tags
  • Repeat these steps for each dependent project.
  • Once all dependent projects have been built, the 'kc' project should be built next. Follow the same steps as above to fetch the new tags and checkout the most recent release tag. However, instead of doing a simple 'mvn clean install', use the following commands to build the project:
    • export VCTargetsPath="C:\Program Files (x86)\MSBuild\Microsoft.Cpp\v4.0\V120"
    • mvn clean compile source:jar javadoc:jar install -Dgrm.off=true -P oracle

Update kc-custom projects

Now we need to merge any Kuali changes into the Tufts custom classes and make any further changes that are necessary to maintain compatibility, or revert changes that clash with our customizations that we want to keep the custom behavior for.

  • Create a second git directory which will contain the previous versions of each project. Clone the 'kc', 'kc-s2sgen', and 'kc-rice' projects into this folder, and checkout the previous branch for each project (the versions we were coming from in the steps above, not the version we updated to).
  • Also clone the current kc-custom project into this folder. (Not strictly necessary, since we'll be working from the copy in the regular git folder, but it's useful to have a 'before' snapshot for troubleshooting or debugging.)
  • We currently have four custom projects to update:
    • rice-impl-custom
    • coeus-s2sgen-impl-custom
    • coeus-impl-custom
    • coeus-webapp-custom
    The rice and s2sgen projects only have a couple of custom files each, so let's update those manually first.

rice-impl-custom and coeus-s2sgen-impl-custom

  • I find it easiest to open up 4 explorer windows in a grid, showing the old base/custom and new base/custom projects, like so:


  • Now, for each file in the "new custom" project, use a diff tool like WinMerge to do two comparisons:
    • Compare the "old base" version of that file to the "new base" version, to see what changes Kuali has made to the file.
    • Compare the "old base" version to the "old custom" version, to see what customizations Tufts has made to the file.

  • Then, update the "new custom" version of the file to accommodate both sets of changes. 
    • In most cases, the Kuali changes and the Tufts changes won't overlap. For these, just merge the new Kuali changes into the custom file. (If there are a lot of Kuali changes, it may be easier to just copy the new Kuali version over into the kc-custom project and re-add the Tufts changes.)
    • In cases where the Kuali changes do  overlap with the Tufts changes, you'll need to make a judgement call about how to merge the two files. If Kuali is making changes to a feature/function that we specifically overwrote with our own logic, we may want to simply keep our code – though it may still require updates if Kuali is changing classes/functions that are used by our custom code. Conversely, if Kuali is making a major overhaul to a class, it might be worth re-examining our customizations to see if they still make sense to keep. 

 

  • Maven pom.xml files are a special case, since these are usually completely re-written for the Tufts custom projects. Usually, all you'll need to do to the pom file is update the version number near the top to match the new Kuali version. 
  • Once the pom.xml and all of the java/resource files in the new rice-impl-custom project have been updated, test out the build with the command "mvn clean package -Dgrm.off=true" to ensure there are no compile errors, then move onto the coeus-s2sgen-impl-custom project and do the same thing.

 

coeus-impl-custom and coeus-webapp-custom

The rice and s2sgen projects only had a few files, but the coeus-impl and coeus-webapp projects (both within the larger 'kc' project) have many, many more. Merging all of these changes is going to take some time no matter how we do it, but we can make our job easier by drilling down on the specific files that have been updated by Kuali since the last update and cross-referencing them with the files that exist in the kc-custom project.

Go to "New base" kc project, and run the following command to generate a list of files changed since the "old" version. The first argument should be the tag of the previous version, and the second arg should be the new tag for the current version. You can change the name of the text file as well.

git diff coeus-1808.0021 coeus-1901.0005 --name-status > kc_1808_1901_changes.txt

This will generate a listing of each file that has been changed in the base code since our last update. You can use this file essentially as a "To-do list" of files that need to be reviewed and merged. 

Since we only maintain custom versions of the coeus-impl and coeus-webapp projects, you can delete all lines related to the other projects (coeus-db, coeus-help, coeus-it, coeus-tool). We also don't customize the test classes (src/test under each project) so those can be removed as well. 

The remaining lines are the files that need to be merged. It may look like a lot, but even within the impl and webapp projects, we've only customized a small portion of the files, so many of these lines will require no action. If you wanted, you could also do a listing of all of the files in the coeus-impl-custom and coeus-webapp-custom projects and do some text processing to generate a list of the files that appear in both places, but I typically just reference the git diff as I walk through the custom projects, ignoring any lines for files that don't exist.

Now you just need to repeat the compare-merge process as above until all of the changes have been reconciled.  

Some additional notes and pointers:

  • The git diff listing will indicate whether each file has been added, modified, deleted, or renamed. Most changes are straightforward modifications, but pay attention to any additions, removals, or renames – these may indicate that Kuali has refactored some code, which could impact our custom code even if the specific files we changed haven't been touched. 
  • The master pom.xml file under kc-custom is different from the others, in that it largely is a copy of the base pom.xml (located at kc/pom.xml). However, we make some changes to the project name and update a few references to use our custom projects rather than the base ones. All of the other dependencies and such will need to be updated, however, so the best way to update this file is the following:
    • Use a diff tool to compare the "old base" pom.xml with the "old custom" pom.xml. This should highlight the handful of customizations we've made.
    • Copy the "new base" pom.xml into the "new" kc-custom project, then manually update the file to include the Tufts changes.
  • There are XML files known as the Data Dictionary files that usually reside in the coeus-impl project under src\main\resources\org\kuali\kra\datadictionary. In the coeus-impl-custom project, however, most of the customized versions of these files are located at src\main\resources\edu\tufts\kuali\kc\datadictionary. The XML files in this location are treated as overrides by the build, and will take precedence over the original files in the other location. But any Kuali changes made to the files under org\kuali\kra should be merged into the same files under edu\tufts\kuali\kc.
  • There are also a handful of custom java classes under coeus-impl-custom\src\main\java\edu\tufts. These obviously won't have Kuali changes to merge in, but it's worth taking a look at their parent classes/interfaces (and other Kuali implementations of those) to see if any changes might be necessary.
  • Occasionally, Kuali will do a bulk update to modify the copyright information in the header of each file, which will result in the diff returning every single file in the project. If this is the case, you can add a regex to the git diff command, using something like this to ignore all comments:
    • git diff -w -G'(^[^\*# /])|(^#\w)|(^\s+[^\*#/])' coeus-1808.0021 coeus-1901.0005 --name-status > kc_1808_1901_changes.txt

Build, Run, and Test

Once all of the merging is complete, you can build the entire kc-custom project using the build-kc.sh script. Then you can fix any compile errors that prevent the build from completing, then deploy the final .war file to tomcat and fix any startup errors, then test out the application and fix any runtime errors. The specifics of that will depend entirely on the changes that were made as part of the update, but if you made it this far down the page, I have faith in you (smile)

Information on the Tufts IT Knowledgebase is intended for IT Professionals at Tufts.
If you have a question about a Tufts IT service or computer/account support, please contact your IT support group.