Introduction
What’s the problem?
I’ve got a Mantis project which I use to manage the development of my project/product. When people commit to the version control repository they reference the Mantis issue number in the commits.
I want one or more of the following:
- Ensure that commit comments do actually reference one or more issues. I don’t think that anyone should be making commits without referencing an issue.
- I want to ensure that the issue(s) which are referenced in the commit comment are assigned to the person performing the commit
- I want to ensure that the issue(s) which are referenced in the commit comment are at the confirmed or assigned state and haven’t already been closed
- I want to ensure that the issue(s) which are referenced in the commit comment belong to the appropriate project
OK, what’s your solution then?
To build on the Source
Integration plugin in
order to implement the checks and to utilise pre-commit hooks in order to make
the appropriate call-backs to Mantis. If the checks performed by the hook don’t
pass then the commit is prevented by the VCS
I don’t think that you should be so rule-happy with commit comments!
It’s a matter of choice – some projects prefer to have a greater degree of control/enforcement than others. All of the checks are optional and none are enabled by default.
I don’t like your software – how else could I do this?
I know of the following:
How To Install
Step 1 : Install the Mantis Plugin.
The code is a branch of the Source Integration plugin. Go here and click the “Download ZIP” link in order to get it.
Copy the contents of the zip file to the plugins directory in your Mantis install.
Follow steps 4-10 of the Source Integration plugin installation guide
Step 2 : Install the Hook
Several example hooks are provided – which one you need to use depends on which version control system you’re using.
Subversion (SVN)
Copy the SourceSVN/pre-commit.tmpl.mantis-checks-commit file from the ZIP to your SVN repository’s hooks directory. Ensure that the file ownership is appropriate it has executable permission set. More information on hooks can be found in the Version Control with Subversion book.
Rename the file within the hooks directory to be pre-commit.tmpl (i.e. remove the .tmpl.mantis-checks-commit extension)
Modify the URL setting to point to the web interface to your Mantis installation. Don’t remove the plugin.php part or the text which follows that.
Modify the PROJECT setting to match the name that you gave the repository when configuring it in Mantis (Part of Step 1).
Modify the API_KEY setting to match that which Mantis is configured to use (again, part of Step 1).
If necessary, update the SVNLOOK and CURL settings to point to where those tools are installed.
Git
TODO
Step 3 : Configure the Mantis Plugin
All that’s left to do now is to choose which checks you want to associate with
the repository. For the purposes of this guide it is assumed that you already
have the basic repository details set up in Mantis as part of your
SourceIntegration configuration. If not then you will need to perform this step
first.
In the Mantis web front-end, select the “Repositories” link, then click the
“Manage” link on the repository you wish to set up commit checking on. Select
“Update Repository” and you will see a list of configuration options. Select
those that you want (see the table below) and click “Update Repository”
| Option | Description |
|---|---|
| Commit Required Issue Reference(s) | When enabled, this check will ensure that the commit comment contains references to one or more Mantis bug IDs. The format of the reference is as per the SourceIntegration plugin’s “Bug Link Regex” settings. |
| Referenced Issue(s) Must Exist | When enabled, this check will ensure that the Mantis bug IDs referenced in the commit comment are associated with tickets which exist in Mantis |
| Referenced Issue(s) Must Be Owned By Committer | When enabled, this check will cross-reference the username of the committer with the username to which the bug ID(s) referenced in the commit comment are assigned. In the case that they don’t all match, the check will fail |
| Committer must be a member of the Mantis project | When enabled, this check will cross-reference the username of the committer and the usernames associated with the Mantis project (see the project’s configuration under “Manage Projects” in Mantis). In the case that the committer is not listed as a project member, the check will fail |
| Committer Must Be A | In the case that the previous check is enabled, this field allows the check to be expanded to limit the access levels at which a commit is allowed. By default, commit is allowed at all levels. |
| Referenced Issue(s) must be at a particular status | When enabled, this check examine the status of the bugs referenced in the commit comment. In the case that one or more of the tickets is not one of the statuses listed in the “Only allow commit when ticket is” list, the check will fail |
| Only allow commit when ticket is | See previous item |
| Referenced Issue(s) must be within a particular project | When enabled, this check cross-references the Mantis projects to which referenced bugs belong and the list specified in the “Only allow commits when ticket is within” option. In the case that one or more ticket is not a member of the specified list of Mantis projects, the check fails. |
| Only allow commits when ticket is within | See previous item |
Step 4 : Quick Test (Optional)
A simple way to quickly test that your set-up is working is to enable the option to enforce issue references in commit comments, then to attempt to commit to the repository without referencing any issues. The commit should be refused. Of course in the case that the installation has not worked correctly, you will actually commit the file, so please be prepared for this!
How to use
If the installation has been successful then all you need to do is ensure that
commit comments reference the appropriate tickets, using the appropriate format
of comments. The format for referencing comments is configured as a regular
expression as part of the Source Integration plugin configuration. By default
it recognises comments containing text such as issue #12 or issue #12,#61, etc.
Potential Problems
The usernames used for version control don’t match those used in Mantis
That’s unfortunate and will require some manual intervention. Possibly the easiest way to work around this is to create a look-up function to return the Mantis username based on the version control user name then modify the hook function to call this.