We have developed an upgrade strategy intended to make it as simple as possible for you to maintain your customizations as you upgrade KFS and to contribute code for inclusion in the delivered software, which will further simplify your upgrades. The keys to working within this framework are...

• Determine what version of KFS you want to work with.
• Create a separate Eclipse project in your local version control for your customizations (see #Eclipse Setup).
• Set the following property in the kfs-build.properties file in your user home directory to load an institution build properties file that will facilitate a build time merge of the delivered code and your customizations.

  # supply the path to a build properties file in the project containing your customizations (tip: use a relative reference)
  institution.build.properties.file=

• Set the following in your institution build properties file as needed.

  # add configuration properties for your implementation (this file will be tokenized along with its delivered counterpart)
  institution.configuration.properties.file=
  # pull new or replacement files into the external security directory
  institution.security.directory=
  # add secure properties for your implementation (this file will be tokenized along with its delivered counterpart)
  institution.security.properties.file=
  # add logging properties for your implementation (this file will be tokenized along with its delivered counterpart)
  institution.log4j.properties.file=
  # pull new or replacement files into the application server used for development
  institution.appserver.directory=
  # create additional directories in and pull new or replacement files into the staging and reports directories 
  institution.work.directory=
  # merge implementation java, xml and property source files into the delivered code for war builds
  institution.source.directory=
  # merge implementation web content into the delivered code for war builds
  institution.web.content.directory=
  # merge implementation test source files into the delivered test suite for automated execution
  institution.test.source.directory=
  # merge implementation libraries into the delivered library
  institution.lib.directory=

• Set other build properties in your implementation properties file to load implementation Spring, OJB, Struts, etc. files that will override and supplement the behavior of the delivered application (also see KFS Customizations).

• Choose the appropriate location for the files that you add in order to override or extend delivered functionality.

  To make things simpler for your developers, we suggest following the structure of the delivered project and simply replacing org.kuali.kfs with an appropriate value for your institution in package names.

• Determine how you will obtain KFS from the Foundation repository for test, training, and production server deployments, if you want to automate those (see #Server Builds).

Eclipse Setup

The setup above should make the normal ant build targets (when run from the base project directory) function properly. However, Eclipse needs a little more tweaking if you want it to compile your code into the necessary location for local development. For this, you will need to make some changes to the .classpath and .project files in the original project. We recommend that you create a patch containing the modifications to .classpath and .project and commit it to your implementation customizations project to simplify things for your developers.

• Create a "Linked Resources" Directory
  • Technically, you can skip this step, but, it does insulate you from path differences between developer machines, since these would need to be absolute paths otherwise.
  • Set up a linked resource path called "PROJECTS_DIRECTORY" with the appropriate path for your system.
    
• Add linked directories for each source path.

  • See the snippet below and adjust for your project name and path.

    <linkedResources> <link> <name>sampleu-src</name> <type>2</type> <locationURI>PROJECTS_DIRECTORY/projectname/src</locationURI> </link> <link> <name>sampleu-test-src</name> <type>2</type> <locationURI>PROJECTS_DIRECTORY/projectname/test/src</locationURI> </link> </linkedResources>

• Add Linked Source Directories to classpath

  • Yes, you can do this with the UI, but editing the .classpath directly is easier.

    <classpathentry excluding="**/.svn/**" kind="src" path="sampleu-src"/> <classpathentry excluding="**/.svn/**" kind="src" path="sampleu-test-src"/>

• Add the libraries to the classpath
  • Edit your build path to reference the libraries from your other project as needed.

Server Builds

When building the application in test, training and production environments, you may need to obtain the version of KFS that you are working with programatically. Here is an example of one way you could do that...

<target name="prepare-project">
    <echo message="ant.lib.directory = ${ant.lib.directory}" />
    <typedef resource="org/tigris/subversion/svnant/svnantlib.xml">
        <classpath>
            <fileset dir="${ant.lib.directory}" includes="svn*.jar" />
        </classpath>
    </typedef>
    <taskdef resource="net/sf/antcontrib/antlib.xml">
        <classpath>
            <pathelement location="${ant.lib.directory}/ant-contrib-1.0b3.jar" />
            <pathelement location="${ant.lib.directory}/bcel-5.2.jar" />
        </classpath>
    </taskdef>
    <deploy:if>
        <isset property="fetch.foundation.kfs" />
        <then>
            <delete dir="${environment.build.directory}/kfs" />
            <svn>
                <export srcurl="${foundation.kfs.svn.url}" destpath="${environment.build.directory}/kfs" />
            </svn>
        </then>
    </deploy:if>
</target>