Collab:VisItWiki commit process

Commit overview

The commit process entails several parts:

  1. Checking each changed file to ensure:
    • There are no spurious print statements
    • All changes are documented in the change log
    • All changes are commented, e.g. in the function prologue
    • All changes meet coding guidelines (see here)
    • (We normally check files using tkdiff).
  2. Issuing an "svn commit"
  3. Communicating your change (see below)

Norms for development

It is expected that the trunk will contain a functioning version of the code. This means that it will, of course, compile, but also hopefully not cause new regressions in the regression suite. It is understood that mistakes happen and that occasionally a compilation problem will work its way into the code. It is not expected that you run the full regression suite before committing. That said, it is considered good practice to run the full regression suite on changes that are considered "risky". Further, it is expected that you fix any failures that come about due to your checkin. We strive to have a pass on the regression suite every night.

Every commit to the trunk must have an accompanying e-mail to the VisIt developers list. Therefore, you should not commit intermediate copies of files to the trunk, even if you are confident that the changes will not break anything. Commits to the trunk incur costs for other developers ("svn update" for those doing trunk development, merging for those doing branches, etc.). Although these costs are necessary, we want to pay them only when necessary.

That said, we often commit what we feel are atomic changes to the code. For example, it is common for a developer to fix a bug, test the fix, commit it, then fix another bug, test that bug, and then commit that fix. The opposite situation, where a developer fixes (and tests) multiple bugs, before committing is acceptable, but we often aim to have each commit fix a specific problem. (Among other things, this makes it easy to track down the history of the code.)

Communicating your commit

Your commit should be communicated in four ways:

  1. To developers, via e-mail. This should be done immediately.
  2. To the user community, via the release notes.
  3. To the bug tracking system
  4. Through formal documentation, if necessary

Commit e-mail

As soon as you finish your "svn commit", you should send an e-mail. The e-mail should be addressed to "visit-commits at ornl dot gov". It should contain the subject line "Update to SVN(rev)" with "rev" being the revision number of the Subversion commit. If there were commits to both a release candidate trunk and the trunk, put both revision numbers, as in: "Update to SVN(RC: 2587, trunk: 2589)".

The e-mail should contain a description of the work that was performed. The length may vary based on the work done. A normal bug fix might merit just a single line, with complicated bug fixes sometimes containing a whole paragraph. Large enhancements almost always require several paragraphs to describe changes in the code to other developers. Finally, the e-mail should contain a list of all files modified. This list is typically taken straight from a "svn status" command.

Release notes

Each release has its own HTML file for release notes, located in the "/src/help" directory. A typical name for this file would be "relnotes1.8.0.html". The release notes are a mechnanism for communicating changes from the last release to this release, including both bugs and enhancements. Each change gets a single entry in the file.

It is your decision whether or not to update the release notes each time you make a change, or right before the release. Most developers do it right before the release, but that mode is really only efficient for people who make *many* changes per release.

Bug tracker

Almost all work in VisIt is associated with a ticket in the bug tracker. Go to ClearQuest and close the bug out.

Formal documentation

Many enhancements change the user interface. If you have changed the interface, you might need to update the documentation. Brad Whitlock will have to describe the norms for our new documentation in this section when it is ready.