dklfgj dfgjmpsdklg dfgjdsklfg dfjglksdfjg sdfgjokdfjg dfgjoksdfjg sdfgjksdlfgjsdf gdgjopksdfgj

Submitting code changes

For major changes please read Process for incorporating major changes

The APSIM Task System¶

All changes must have a task entered into the Task system.

The APSIM Build System¶

The APSIM development team use a continuous integration system where all changes are automatically built and tested using the APSIM test suite. To facilitate the submitting of changes and the scheduling of builds and tests, a dedicated computer has been setup with a web interface. The entry point into the APSIM Build System can be found here.

The APSIM Build System shows a list of build jobs, whether they are queued for building and testing, whether they are currently running, or whether they have already run and have passed or failed. For jobs that have passed, the build computer will create 2 additional zip files, one of all binary files in the Model directory and one of the entire build tree. It will also create two installations, one for release and one containing all modules.

Prerequisites¶

Before you submit changes to the APSIM repository, you will need:

• a full APSIM development tree with binaries
• a copy of a command line SVN client

To get these, read the page on Building Apsim.

Creating a patch¶

All changes to the APSIM version control require the submission of a patch. A patch is a single .zip file that contains diffs of 1 or more files. To create the patch, you will need to use the CreatePatch.exe application. This can be found in your Model directory in your development tree. Before running this tool, you will need to create a shortcut to it that has the Start in directory set to the root of your development tree e.g.


This shortcut can reside anywhere.

When you run the shortcut, a list of files will be displayed that you have modified (the command line SVN client is used to obtain this list). Tick the files you want to include in the patch and click OK. Save the patch file (.zip) somewhere to your hard disk and then select "Yes" you do want to upload it to the build system.

Submitting a patch to the APSIM Build System¶

Goto APSIM Build System.

Clicking the Upload job button will allow you to upload your patch.
You will need to enter your APSIM SubVersion user name and password, the task that relates to the patch, a description of the changes, the name of the patch file on your hard disk and whether you want the build system to do a SubVersion commit if the patch job passes. When you've entered the information, click Upload patch

Investigating failed build jobs¶

A job is said to have failed when 1 or more tests (diffs) have given different results to what is expected (in version control). A job can also fail if the source code doesn't compile properly. If all tests run and give the same results as in version control, then a patch is said to pass.

When a job passes, it is automatically committed to version control (if the submitter ticked the commit option when uploading the patch). When a job fails, the submitter of the job can check for source code compilation issues by clicking on the link in the details column for their job. If the NumDiffs column shows 1 or more diffs, then some tests have produced unexpected results. To discover which ones, the submitter can click on the link in the Diffs column. This will download a zip file containing all files (including the ones uploaded in the patch) that are different to version control. Once a zip file has been unzipped, the submitter can right click on the top level folder and goto TortoiseSVN | Check for modifications. This will provide a convenient way to look at all diffs.

If the diffs are what you expected then you can create a new patch of source code and the output / summary files and resubmit a new patch to the system.

For more information on the process and types of tests in the suite, read the following paper:

Holzworth, D. P., N. I. Huth, and P. G. deVoil. 2011. Simple software processes and tests improve the reliability and usefulness of a model. Environmental Modelling & Software 26:510-516.

Submitting a Patch containing a New Module¶

These instructions assume that you have already tested the new module on your own computer. The additional steps for a new module:

• ensure that you have an appropriate Makefile in the module source directory. Copy an existing Makefile from the directory of another module developed in the same language and change the references to the project name
• add the source directory, the model XML and all the Tests and Examples into version control using your SVN client
• edit %apsim%\Model\Build\BuildAll.xml to include your new module. Scroll down the file to find a module that does a similar job (the order that the jobs are executed matters somewhat) and copy and edit the similar job to point to your new module.
  

You should now be ready to create the patch as described above. The patch should include:

• the source file(s)
• the makefile
• the project and solution file and the 'Properties' subdirectory if it is a .NET module
• all the Test and Example simulations including summary and output files
  

Subsequent patches should include:

• the source file(s)
• any intended changes to the Test and Example simulations