In this page

Overview

This page is about implementing the Commit Policy Plugin with the Subversion version control system. For non-Subversion-specific information, please see the starting page of the user manual.

Working with Subversion commit policies

Subversion commits

Subversion rejects your commits immediately if those do not satisfy the conditions of the corresponding commit policy. To fix the problem, just rewrite the commit message or modify the file list to be committed, and then re-commit your changes.

Fixing rejected Subversion commits

You can simply re-commit with the Subversion commandline client like this:

svn commit -m "PLYR-419 fixed: closing the video outstream"

When using a Subversion GUI client, similarly, commit again with the correct commit message and file list.

Subversion branches

(since 3.0.0)

Subversion branches are supported by the Commit Policy Plugin.

You can create a new Subversion branch from trunk using a so-called server-side copy like this:

svn copy http://svn.example.com/repos/calc/trunk http://svn.example.com/repos/calc/branches/FOO-123-faster-compression -m "Start branch"

Branches are verified by the branch rules right before being created in the server-side.

It is important to understand that branch conditions will verify both the branches themselves at creation and the commits on those branches any time later.

Fixing rejected branches

You can simply re-try creating a branch with the correct name using the Subversion copy command (shown above) again. It's that simple.

Subversion tags

(since 3.0.0)

Subversion tags are supported by the Commit Policy Plugin.

For Subversion, a tag is nearly identical to a branch in the sense that both are just directories.

You can create a new Subversion tag from trunk using a so-called server-side copy like this:

svn copy http://svn.example.com/repos/calc/trunk http://svn.example.com/repos/calc/tags/2.3.4-beta -m "Release 2.3.4"

Tags are verified by the tag rules right before being created in the server-side.

Fixing rejected tags

You can simply re-try creating a tag with the correct name using the Subversion copy command (shown above) again.

Subversion merges

Subversion merges are supported by the Commit Policy Plugin.

Merging a branch in Subversion results in a new commit. That is verified by the Commit Policy Plugin the same way as any other "regular" commit.

Verifying branches and tags

This is very important to understand that Subversion has no internal concept of a branch or a tag. A branch or a tag is just an ordinary directory with the additional meaning "attached" to it by the user.

This means that you can can take two approaches to verify Subversion branches and tags with the Commit Policy Plugin:

  1. verifying the branch or tag names (automatically found by the app using its internal, configurable mechanism)
  2. verifying the change paths (i.e. the directory names that represent the branches and tags)

The following sections compare these approaches.

Verifying the branch and tag names

(since 3.0.0)

This is the recommended and elegant approach.

First off, this is important to understand how does Commit Policy Plugin recognizes branches and tags if those are just ordinary directories? When a new branch is created (or deleted) or a change is committed to the repository, the app processes each changed paths. It matches the configurable Subversion branch pattern to the changed files' paths to find the branch name. For example, if the commit contains files from the branches/my-branch folder and its descendant directories, then the branch my-branch will be recognized.

Tags are found in the same way by matching the Subversion tag pattern to the change paths.

With the branch and tag name found this way, you can:

  • add branch conditions to the Branch rules in a commit policy
  • add tag conditions to the Tag rules in a commit policy
  • enter the branch names to the "Apply this rule only where the branch name matches" field of a rule for scope limiting

Verifying the changed paths (directory names)

In pre-3.0.0 app versions, this was the only approach available. Modern app versions still allow using this low-level approach, but it is less intuitive than the one above. Nevertheless, it may be useful in some situations.

No suprise, this approach is also based on the idea that for Subversion, a branch and a tag is nothing else, but a directory. And, as there are two conditions to verify directories (complete change paths, to be precise), you can use the same conditions to verify branches and tags, too:

  1. "Changed paths (files) must match a pattern" condition
  2. "Changed paths (files) must contain issue keys from a JQL query" condition

For example, to accept commits only on the branch my-branch, use the "Changed paths (files) must match a pattern" condition with the branches/my-branch/* glob.

Also, you can limit the scope of a rule to a branch by limiting the rule to the directory that represents the branch. For that, enter a pattern to the "Apply this rule only for the files where the file path matches" field under "Limit scope". It is important that you have to use absolute paths here, like the branches/my-branch/* glob.

Important: unlike the other approach, this one cannot verify the creation of the branch itself, only the commits on it. For example, you can create a branch using svn copy even if its name is disallowed, but then all commits on that will be rejected.

Further reading

More about Subversion hooks

The hook scripts that are auto-generated by the Commit Policy Plugin can be easily installed into Subversion repositories, and the app guides you through the process.

Nevertheless, if you wanted to understand what happens under the hood, see the Implementing Repository Hooks chapter in the Version Control with Subversion book. Another short blog posts on this topic is An Introduction to Subversion Hook Scripts on Windows.

When you use the Commit Policy Plugin to enforce issue keys in the commit messages, you should also try the Jira Subversion Plugin. That app will display the commits mentioning a specific issue key in the View Issue screen, giving you a nice history of Subversion commits related to that issue. They really play together really nicely: Commit Policy Plugin encourages a good practice, and then the result is made visible by the Subversion Plugin.

Questions?

Ask us any time.