The ADCIRC development strategy consists of the maintenance of two separate versions at any given time: the stable version and the development version. The stable version only receives bug fixes, while the development version receives bug fixes as well as new features.

• Current Stable Version: v47
• Current Development Version: v48

At some point, the development version will become stable. At that time, a new developement version will begin, and the major version number will be incremented, e.g., v48.xx will become the next development version as v49.00.

In the past the minor version number was changed each time there was a change in the code and the code was about to be distributed.

Now that svn is being used, the minor version number will be incremented on the stable version just prior to each successive public release. For the development code, the minor version should be updated each time a development branch is merged to back to trunk.

ADCIRC has had many individual contributors and has received code accretions over many years. A set of uniform coding standards has not been defined, and as a result, ADCIRC contains many different styles of Fortran. This section provides a new set of style guidelines for contributing code to ADCIRC.

1. IMPLICIT NONE at the beginning of each subroutine.
2. Fixed form, never exceeding the 72 column limit, even for comment lines.
3. When adding code to an existing subroutine, make the new code match the style of the surrounding code, even if you'd prefer another style.
4. …

1. When adding code that will be used in slightly different ways in different contexts, make it a subroutine, rather than cutting and pasting several times and making small changes to each cut-and-pasted section. Although it is faster to write code with cut-and-paste, the resulting code is harder to maintain, since each cut-and-pasted section will have to be modified individually. Also, it is easier to make mistakes when working with cut-and-pasted code.
2. Rick has expressed a desire for greater modularity … particularly with the number of variables in the global module. When adding a major new feature, please consider the modularity of the data it requires. In other words, if new variables can be made private to a particular module rather than global, please do so.
3. …

We don't have a formal release process, but we need one. It should consist of:

1. Set and stick to a list of new features as the goal for the new release.
2. Have a consensus among us that the goal has been achieved.
3. Run tests that cover the new features as well as making sure old features still work.
4. Fix issues revealed by failed tests.
5. Tag the code as beta and distribute it to collaborative users to make sure their runs perform as expected on the new code.
6. Fix issues revealed by user dismay.
7. Update the docs to reflect the changes. If input files or file formats have changed, produce release notes to highlight the changes.
8. Publicly announce, release, and brag about a shiny new version of ADCIRC.

These tests are often referred to as “regression tests,” i.e., a means to detect a regression in correctness or functionality due to changes in the code. A regression test suite can be build up pretty easily. There are a number of small test cases out there, so the initial set of tests should consist of those. We may also want to differentiate between tests for correctness and tests for functionality. The former is making sure you're getting the expected model results and the latter is making sure that nothing is broken (i.e., adcprep, i/o, message passing, etc).

Testing can get pretty complicated, but it would really just require a couple of small test cases and (most importantly) some sort of testing framework that automates much of it. Brett Estrade has volunteered to help with the framework part of it.

The test suite gets built up based on different purposes. One may want to exercise more options and more cases, but it is also important to test for known bugs that might have been reintroduced. In otherwords, once a bug is discovered and fixed, a test should be created specifically for that bug to make sure it doesn't appear again.

And lastly, a small test suite should be included with each distribution and a more comprehensive should be created that runs during development and before a release.

Subversion is a version control system. That is, it provides a means for many software developers to collaborate on a single software project.

Subversion stores the code in a repository on a central server. In our case, it is stored at RENCI and access control is handled by Brian Blanton. A software developer makes a contribution by checking out the latest version of code, making changes, and then committing the change back to the repository. The rest of us then update our local copy of the code from the repository in order to stay in synch with the latest version of the code.

Subversion repositories consist of a trunk, which is the mainline code, and any number of branches. A branch may be created by a developer that has a lot of changes to make over a longer period of time. This lone developer can work on a branch without affecting the mainline code. Once the changes in the branch are satisfactory, the branch can be merged back to the trunk, making the changes available to all.

Working with subversion requires greater coordination among ADCIRC developers. For example, if two developers change the same file in two different ways, the commit phase will fail. In other words, the Subversion program does not know which changes to accept. Furthermore, if one developer makes changes to trunk that prevent the code from compiling, it will be difficult for other developers to continue working if they update to the latest code. As a result, ADCIRC development with Subversion will adhere to the following policies:

1. Communicate. Jason Fleming is responsible for making sure ADCIRC development is smooth, pain-free and productive—when in doubt, email him.
   1. Also use the adcirc-dev mailing list to keep everyone informed of what you are doing.
   2. If you are not on the adcirc-dev mailing list and would like to be, email Jason Fleming.
2. Make a branch to develop new features, rather than making changes to trunk.
3. Don't commit changes to trunk that prevent the code from compiling, at least on your platform. You must confirm that your code compiles
   1. With and without netCDF
   2. With and without ESMF
4. …

Comprehensive documentation for Subversion is available: http://svnbook.red-bean.com/.

The ADCIRC code is hosted at the following Subversion repository location:

https://adcirc.renci.org/svn

To check out the code, please type

svn checkout https://adcirc.renci.org/svn/adcirc48

In the future, the code will probably be moved to a repository called “adcirc” rather than “adcirc48” etc. The existing names are the result of initial experimentation with creating repositories with different codebases, and it just happened to stick.

Here are a few examples of things that we commonly do with svn.

In order to see the changes between revisions of the repository, type (for example)

svn diff  -r 15:16 owiwind.F

In order to create a tar file that contains just the ADCIRC code and excludes the .svn directories, the first step is to export the code to a new subdirectory. For example:

svn export ./trunk ./adc99_99 

Would copy the local files under version control from the trunk subdir to the adc99_99 subdir, excluding the .svn files. Particular revisions of the svn repository can also be extracted, see the svn documentation for details on how to do this.

One advantage of using svn is that it is easy to go back to an older version of the code, if necessary. The first thing to do in this case is usually to look at the svn log to see what changes were made, so that you can select the right version of the repository to extract. Go to the subdirectory of the code tree that you want an older version of and issue the command

svn log

Look at the log entries, and note the revision that you'd like to extract. Let's say you want to retrieve adcirc48/trunk at revision 65 of the repository (for example). Issue the following command:

svn checkout -r 65 https://adcirc.renci.org/svn/adcirc48/trunk

To make a branch off trunk to add a new feature and call it the myfeature branch:

svn copy https://adcirc.renci.org/svn/adcirc48/trunk https://adcirc.renci.org/svn/adcirc48/branches/myfeature --message "Creating branch to add myfeature"

Then to start using the newly created branch:

svn checkout https://adcirc.renci.org/svn/adcirc48/branches/myfeature