Lisa and Tom's Blog

Redwhat?

First off, what the hell is this Redmine thing? In short, it’s an Open Source tool for projects and not just technical ones, although it is geared more towards that. It has all the things you’d expect including forums, wikis, issue tracking, source control integration, news, files, activity and project management type things (issues can be children of other issues and you can see % complete, Gantt charts for critical paths etc). You can also extend it with plugins – I have one called Embedded which lets you put javadocs up on your project’s page.

My dev environment

Last year I started having a play with Redmine after someone at work showed me it. I have Ubuntu 11.10 Desktop installed on my server (I use it as a media server connected to the TV as well as normal server stuff) and installation was relatively simple. Relatively simple rather than very simple because it uses Ruby on Rails and has dependencies in that which the normal package couldn’t handle, or just wasn’t set up to. Since then I’ve gone a few steps further and got issues integrated with Eclipse without too much hassle. What I’ve also done is set an SVN hook to check that all commits are against a valid, open issue and another to build the project and javadocs once the code is committed. The built code and javadocs are immediately available to use although it’s not quite continuous integration because any existing processes aren’t stopped automatically. What I haven’t used Redmine for much (at all *cough*) is its project management tools, eg Gantt charts. Why? What developers create Gantt charts for their home projects!?!?

How do I set it up

So you think some sort of project resources (wikis, forums etc), Eclipse, issues and source control integration is a good thing? Good on ya, so do I! And you like using Open Source tools? Me too! So let me help …

There are numerous resources for installing Redmine, SVN and Eclipse on many platforms so I’m just going to assume that you already have them installed. I’ll also assume that you’re able to access Redmine through an Apache webserver. During this example we will:

1. Add a Redmine project
2. Setup Eclipse to see and edit Redmine issues
3. Create an issue in the Redmine project from Eclipse
4. Add an Eclipse project to the SVN repo
5. Add the SVN hooks
6. Implement the code for the issue
7. Commit the code
8. Close the issue from within Eclipse

Add a Redmine project

Go to your Redmine site and select Projects from the top menu bar. Then select New Project from the page menu (top of the white section) and set the name and identifier how you like. Click Save. Done – simple as, eh?

Setup Eclipse to see and edit Redmine issues

This one’s a little more complex – although it’s probably the hardest thing out of all the steps. You need to install 2 plugins, one within Eclipse and one within Redmine.

To install the Redmine plugin, go to your Redmine installation (/usr/share/redmine) and run these 2 commands:

git clone git://redmin-mylyncon.git.sourceforge.net/gitroot/redmin-mylyncon/redmine-mylyn-connector ruby script/plugin install redmine-mylyn-connector

Now restart Redmine (I tend to restart Apache so that the Passenger module restarts – seems to do the trick)

To install the Eclipse plugin, in  Eclipse, go to Help -> Install New Software. Use this update site “http://redmin-mylyncon.sourceforge.net/update-site/N/” and install the plugin Mylyn Integration -> Mylyn Connector: Redmine

(There was a screenshot here but it appears to not work)

In Eclipse, go to Window -> Show View -> Other, then select Mylyn -> Team Repositories. In the top-right corner of the view, select the “Add Task Repository” button. Select Redmine as the type, click Next and then set the Server, User ID and Password for your install/account. The Label can be anything (mine is just Redmine – this is what I assume you’ve called yours for this guide). Click Validate Settings and then Finish.

Now open the Task List view – Window -> Show View -> Task List. You should see Redmine (or whatever you chose as your label). Using the New drop-down list icon in the top-right corner you can create new queries – these allow you to create filters/meaningful subsets of the issues. I have a few queries, one is for open issues which are assigned to me so I can quickly see what work I need to be doing.

Create an Issue in the Redmine project from Eclipse

In your Task List view, click the New drop-down list icon and select New Task … Select Redmine and click Finish. Enter a title – for old time’s sake let’s call it “Hello World” – select your project from the Project’s list and enter a brief description. Click submit. To check it worked, go visit your project in Redmine and have a look at the Issues tab.

Add an Eclipse project to the SVN repo

This assumes you already have a repository. If not, there are numerous articles out there showing how to create one. This also assumes you have an SVN integration installed in Eclipse (I use Subversive). Open the SVN Repositories view and add your repository. Right click and select the Find/Check Out As … option. Create a new Java project and call it anything you want. Check in the new project structure/files.

Add the SVN hooks

Change to your SVN repository’s directory on your filesystem (there should be a folder called hooks). Go into the hooks folder.

Put the following contents in a file called “pre-commit”

#!/bin/bash

REPOS=”$1″
TXN=”$2″ 

cd `dirname $0`

# Note that we can rely on PATH containing /usr/local/bin:/bin:/usr/bin
# so take advantage of this.
SVNLOOK=svnlook
MYSQL=mysql
MSGREGEX=”^task\s*([0-9]+):[.\s]*”

MESSAGE=$($SVNLOOK log -t “$TXN” “$REPOS”)

# Make sure that the log message contains some text.
if [[ $MESSAGE == “” ]]
then
   echo “No log message.” 1>&2; exit 1;
   echo “Log message empty” > check_ticket.out.txt
else
   echo “Log message is:” $MESSAGE > check_ticket.out.txt
fi

# Make sure that the log message references a Redmine issue.
if [[ $MESSAGE =~ $MSGREGEX ]]
then
   echo “Found” ${#BASE_REMATCH[*]} ” regex matches” >> check_ticket.out.txt
else
   echo “Commit failed. To commit please specify a Redmine issue number on the first line, e.g.:
    task 1234″ 1>&2; exit 1;
   echo “Could not match ticket number using” $MSGREGEX >> check_ticket.out.txt
fi

REDMINE_ISSUE=${BASH_REMATCH[1]}
SQL=”SELECT COUNT(*) FROM issues I INNER JOIN issue_statuses S ON S.id = I.status_id WHERE S.is_closed = 0 AND I.id = ${REDMINE_ISSUE};”
echo “Found task #\”"$REDMINE_ISSUE”\”" >> check_ticket.out.txt
echo “Checking task exists:” $SQL >> check_ticket.out.txt
REDMINE_ISSUE_OPEN=$(${MYSQL} -N -u redmine_readonly redmine_default -e “$SQL”)

if [[ ${REDMINE_ISSUE_OPEN} -eq 0 ]]
then
  echo “Commit failed. Redmine issue #${REDMINE_ISSUE} is not in an open state.” 1>&2; exit 1;
fi
echo “Commit allowed” >> check_ticket.out.txt

In the file “post-commit” put the following contents

date=`date`

echo $date > /tmp/post-commit.out.txt

Implement the code for the issue

In Eclipse, go to Window -> Preferences. Select Mylyn -> Team an set the Commit Comment Template to be:

${connector.task.prefix} ${task.key}: ${task.description}

Go to your Task List view, find the task you created, right-click it and select Activate

Go the the Synchronize view and click Synchronize.

Go and create a class in your source folder (in the Package Explorer view you might need to deselect “Focus on Active Task” to be able to see you project).

Commit the Code

Go back to the Synchronize view, right-click your task and click Commit. Notice that the comment is already populated with your task number and description (matching the regex in the pre-commit hook). Click OK and check that (on the machine hosting your SVN repository) that the file /tmp/post-commit.out.txt contains the current date.

Close the Issue from within Eclipse

Go back to the Task List view and open your task. Scroll down to the bottom and change the Mark as field to Closed. Click Submit. Bingo. Bob’s your uncle etc etc. You’ve just committed code against a redmine issue and created an SVN hook to ensure that’s the case

What else can I do with this?

Um, pretty much anything you want!

For example my post-commit hook is much more complex. I have a location on the server where each project is checked out. Each project also has an ant script to build the project and the javadocs. The post-commit hooks changes to the project’s checked out folder, updates the project, builds it and the javadocs and deploys the built version.

Why not try changing the Mylyn template comment format and commit code – it will fail because it can’t work out what you’re committing against. You could extend the pre-commit hook to also check that the issue you’re committing against was raised against your project (or one of it’s parents), rather than just being any old open ticket.

If you’re doing anything interesting with your install, add a comment and let me know!