SVN Commit Policy

Problem

In general, we are trying to mitigate the risk that changes produce unnoticed bugs.

Branch Rules

There are many different types of branches in the VisIt tree, with differing commit policies. Note that these rules only apply if you have commit access to the repository; if you are simply sending patches to another developer for inclusion, they are expected to adhere to these policies on your behalf.

Trunk

Anything is clear for the trunk. You do not need to clear any commits with the consent of developers prior to doing so. It is preferable that you verify changes pass the test suite prior to committing, but not required.

Email: All trunk commits require a notification to the developer mailing list.

Personal Branch

Personal branches reside in /branches/username/branch_name. There are no restrictions on what can be committed to a personal branch.

Email: You should not inform other developers of personal branch commits.

Release Candidates

Release candidates are special branches which are used to stabilize a release. They are feature-frozen and otherwise fairly `cold.' The idea is that we don't want to put large changes into a release candidate, even to fix a known bug. Minor changes or changes which are exceedingly localized (e.g. a new database) are acceptable for an RC.

Email: A good rule of thumb is that any change which affects more than `you' and `your users' requires team consensus prior to the commit. At that point, you need to email the developer mailing list and justify your commits. In particular, you should:

  • Explain the issue with the current RC
  • Explain why this fix should make it into this release. Why can't it wait for a patch/later release?
  • Preferably, detail the subsystems you think will be affected.

Patch Releases

Patch releases are derived from branches forked from a X.Y.0 release, sometimes referred to as a `dot-oh' release. Except in extreme circumstances, these should not require:

  • changing state objects
  • modifying header files
  • adding new files

Small `master hacks' which fix the problem are preferred over larger changesets which address root issues. In that case, the root issue should be addressed by another commit in the trunk.

The rationale for this case is that version X.Y.Z for Z != 0 (i.e. patch releases) should be compatible with the primary version X.Y.0. By "compatible," we mean that use cases such as a version X.Y.Z client installation which utilizes a version X.Y.0 server installation should work without issues (and vice-versa). Patch branches may or may not be built for all supported architectures, so it is critical that it does not break when utilized with any other versions in the same release series.

Email: All patch branch commits require a notification to the developer mailing list.

Enforcement

The team has decided on implementing subversion repository hooks to help enforce these policies. In particular, these hooks should notice when a user is doing a change which potentially violates these policies, and print out a warning for them.

Implementation

Subversion's post-commit script will detect when a header file is changed in a patch release, and report back with an error. This translates to a warning for the user of the subversion client -- since this is the post commit script, we couldn't abort the transaction here even if we wanted to.