I recently installed Subversion and Mantis on my Linux server for handling version control and issue tracking of my software projects. I also use the excellent Eclipse IDE for all my development whether it be Java, C++ or PHP. This post details how I managed to integrate all these tools together so that I could commit my code changes straight from Eclipse into my Subversion repository and also automatically update an associated issue report in Mantis.
The basic steps are as follows:
- Installing Subversion and WebSVN
- Installing and Tweaking Mantis
- Add a Subversion Post-Commit Hook
- Installing Subclipse
- Adding BugTraq Properties
The information on this page came from multiple sources, but most of the credit goes to Marc on the Mantis forums for providing the necessary code modifications to mantis.
1. Installing Subversion and WebSVN
First off I installed Subversion and WebSVN (a web interface onto your Subversion repository) on my Ubuntu Linux server.
To install Subversion I ran:
sudo apt-get install subversion
and configured a single repository in /var/lib/svn.
I then installed the latest version of WebSVN by doing:
wget http://websvn.tigris.org/files/documents/1380/45918/websvn-2.2.1.tar.gz sudo apt-get install enscript cd /var/www sudo tar xzf ~/home/david/websvn-2.2.1.tar.gz sudo cp websvn-2.2.1/include/distconfig.php websvn-2.2.1/include/config.php
I then edited websvn-2.2.1/include/config.php and changed the following settings:
$config->addRepository('Default', 'file:///var/lib/svn');
$config->useEnscript();
$config->useBugtraqProperties();
This has told WebSVN where my repository is and that I want to use Enscript for syntax highlighting. The last line tells WebSVN to lookout for some special properties on the repository that will link it with the Mantis issue tracker – more on this in a bit.
2. Installing and Tweaking Mantis
Mantis is is a free web-based bug tracking system. It is written in the PHP scripting language and works with MySQL. I’m using version 1.2.0a3 here. Simply download the .tar.gz file, unpack it and follow the setup wizard at http://yourserver/mantis/ to configure it.
To get Mantis to integrate with Subversion and WebSVN I had to make a few tweaks to some of it’s PHP files. The instructions I followed were based on the ones I found here: http://www.mantisbt.org/bugs/view.php?id=8070.
Note that you will need to add a new user to Mantis that Subversion will use to add notes to issues. I have created a user called svn and given it Developer access to my projects.
Edit plugins/MantisCoreFormatting/MantisCoreFormatting.php and after every line that says:
$t_string = string_process_cvs_link( $t_string );
add another line that looks like this:
$t_string = string_process_svn_link( $t_string );
There should be 3 in all.
Next, edit mantis/core/string_api.php and add this code:
# process the $p_string and convert filenames in the formats
# SVN:rev:U full/path/filename.ext
# SVN:rev:
# into URLs pointing to the WebSVN server.
# 'rev' is the revision number.
# 'U full/path/filename.ext' is the output format
# of 'svnlook changed'.
#
# if $p_include_anchor is true, include an <a href="..."> tag,
# otherwise, just insert the URL as text
function string_process_svn_link( $p_string, $p_include_anchor=true ) {
$t_string = $p_string;
$t_svn_web = config_get( 'svn_web' );
$t_svn_web_repname = config_get( 'svn_web_repname' );
$t_svn_web_showdiff = config_get( 'svn_web_showdiff' );
$t_svn_web_file_page = $t_svn_web_showdiff ? "diff.php" : "filedetails.php";
$t_status['A '] = 'added: ';
$t_status['D '] = 'deleted: ';
$t_status['U '] = 'modified: ';
$t_status['_U'] = 'props: ';
$t_status['UU'] = 'mod+prop: ';
if ( $p_include_anchor ) {
$t_file_replace_with = "$t_status['\2'].'<a href="'.$t_svn_web.$t_svn_web_file_page.'?repname='.$t_svn_web_repname.'&sc=1&path='.urlencode('/\3').'&rev=\1" target="_blank">\3</a>'";
$t_rev_replace_with = 'Revision: <a href="'.$t_svn_web.'listing.php?repname='.$t_svn_web_repname.'&sc=1&path=%2F&rev=\1" target="_blank">\1</a>';
} else {
$t_file_replace_with = "$t_status['\2'].': \3 - '.$t_svn_web.$t_svn_web_file_page.'?repname='.$t_svn_web_repname.'&sc=1&path='.urlencode('/\3').'&rev=\1'";
$t_rev_replace_with = 'Revision: \1 - '.$t_svn_web.'listing.php?repname='.$t_svn_web_repname.'&sc=1&path=%2F&rev=\1';
}
# files
$t_string = preg_replace( '/SVN:(d+):([ws]{2})s{2}([/w.s]+)/e', $t_file_replace_with, $t_string );
# revisions
$t_string = preg_replace( '/^SVN:Revision:s*(d+)/m', $t_rev_replace_with, $t_string );
return $t_string;
}
# --------------------
Now edit mantis/config_inc.php and add the following:
# --- Source Control -------------- # Account to be used by the source control script. $g_source_control_account = 'svn'; # $g_source_control_notes_view_status = VS_PUBLIC; # Regular expression used to detect issue ids within checkin comments. $g_source_control_regexp = '/bMantis ID #(d+)b/i'; # --- SVN linking --------------- # Converts SVN filenames into URLs pointing to your WebSVN server # (e.g.: 'SVN:513:trunk/myproject/readme.txt') # # insert the URL to your WebSVN server # eg: http://www.mydomain.org/WebSVN/ # (include trailing slash, no php filename) $g_svn_web = 'http://yourserver/websvn/'; # the WebSVN name of the repository # (WebSVNs $config->addRepository()) $g_svn_web_repname = 'Default'; # when showing a file, WebSVN can either display # a diff with the previous version (ON) or # the whole file contents (OFF). $g_svn_web_showdiff = ON;
Phew, that was quite a lot of work, but we’re all most done! What we have just done is modify Mantis to parse commit messages from Subversion and if the message contains [Mantis ID: #n] it will automatically add a new note to the corresponding issue containing the commit message and add hyperlinks to WebSVN to view diffs for all the modified files.
3. Add a Subversion Post-Commit Hooks
Before Mantis can parse our Subversion commit messages we actually need to tell Subversion to pass them to Mantis which we do using a Subversion post-commit hook. The post commit-hook is simply a shell script that Subversion executes after a commit has been made to the repository. The commit-hook is based on the one found here: http://www.mantisbt.org/bugs/view.php?id=8070. It takes the repository location and revision ID and then uses the svnlook command to lookup the commit message and list of modified files. It then constructs a message that is passed to Mantis by calling it’s checkin.php script.
Create the file /var/lib/svn/hooks/post-commit and add the following:
#!/bin/sh REPOS="$1" REV="$2" SVNLOOK=/usr/bin/svnlook PHP=/usr/bin/php MANTIS=/var/www/mantis/scripts/checkin.php COMMIT_MSG=`$SVNLOOK log -r $REV "$REPOS"` CHANGED_FILES=`$SVNLOOK changed -r $REV "$REPOS" | sed s/^/SVN:$REV:/` $PHP -f $MANTIS <<zzzMantiszzz $COMMIT_MSG --- Changed Files --- SVN:Revision: $REV $CHANGED_FILES zzzMantiszzz
Be sure to make the script executable with
chmod a+x /var/lib/svn/hooks/post-commit
Now when we make a commit that contains [Mantis ID: #n] a new note will automatically be added to the Mantis issue:
4. Installing Subclipse
Eclipse already has support for CVS under the Team menu. Subclipse is plug-in that adds a Team Provider for Subversion. This allows checking in and out straight from Eclipse!
The easiest way to install Subclipse is to go to the “Software Updates and Add-ons” and add a new site: http://subclipse.tigris.org/update_1.6.x. More detailed installation instructions are available on the Subclipse website.
To set a project up to use Subversion do the following:
- Create a new project in Eclipse, or open an existing one.
- Right-click on it and select
Team->Share Project...from the pop-up menu. - Select
SVNas the repository type. - Set the repository location as
svn+ssh://yourserver/var/lib/svn. - Finally select a name for the project and perform the initial commit.
5. Adding BugTraq Properties
Currently to link a commit to a Mantis issue we have to include [Mantis ID: #n] somewhere in our commit message. Using BugTraq properties we can get Subclipse to automatically provide a extra input field for the Mantis issue ID which is separate from the commit message. Additionally Subclipse can even provide a warning message if we forget to enter a Mantis issue ID.
Subversion properties are “metadata” that can be attached to files and directories. This metadata is primarily intended to be used as processing directives by client applications (e.g. Subclipse). BugTraq is a set of properties for a standardized way of integrating Subversion clients and third party bug tracking software. The original spec can be found at: http://tortoisesvn.tigris.org/svn/tortoisesvn/trunk/doc/issuetrackers.txt (You’ll be prompted for user id and password, use “guest” with no password).
The main properties that I am using are:
bugtraq:url– This is the URL to the Mantis issue page.bugtraq:label– This is the text that Subclipse will show when asking for the issue ID.bugtraq:message– This is the text that will be appended to the commit message.bugtraq:warnifnoissue– This can be set to display a warning if no issue ID is entered.
These properties must be set on the top level directory of each project in the Subversion repository. These properties can be added to a project using Subclipse by right-clicking on the project and selecting Team->Set Property.... This action needs to be performed several times to add the following properties:
bugtraq:url http://yourserver/mantis/view.php?id=%BUGID% bugtraq:label Mantis ID: bugtraq:message [Mantis ID #%BUGID%] bugtraq:warnifnoissue true
Now when you perform a commit from Eclipse the commit dialog will have a text field for you to type in the Mantis issue ID. Eclipse will then take care of adding the magic [Mantis ID #n] tag to your commit message.
