YouTrack Issue & Bug Tracker

You know what makes YouTrack different from other Issue Management Systems? It’s focused around simplicity and productivity. And those aren’t just marketing hooks to get your interest spiked. YouTrack is genuinely about making it easier for you as a developer to manage issues, bugs, tasks and allow you to focus on what you enjoy, which is writing code. With its insane keyboard navigation, but more insanely productive command system, it lets you get the job done with minimum effort. Of course, it also offers a nice User Experience for the non-technical crowd too, so it fits everyone.

In this upcoming webinar we’re going to introduce you to YouTrack, but you’re going to see it in the context of how its meant to be used. We’ll cover project creation, working with issues, both individually as well as in bulks, customizing issues, powerful searches and more.

When: Thursday 19th of April 2012. 15:00 to 16:00 CET (Central European Time)

By: Your hosts

Valery Andrianova         Hadi Hariri

(Yes, I know, no comparison whatsoever)

Where: You set the terms of where you want to view this from (Sofa, Desk, Bed). Just make sure you register

We hope you join us!

I had to set up a new project yesterday on YouTrack and needed to customize some of the default status fields. One of the ones I added was a ‘Paused’ status, for those times when a task gets held up for whatever the reason. Adding a custom value is pretty simple to do: under Administration, select the project, click on the the Fields tab, and click on the Value Bundle link of the field you want to update, in my case the State field

Once there, select Add State and type in the new value. You can give it a description and an optional color. I chose an orange tone to indicate its paused [Resolved checkbox indicates if the state represents the issue as resolved].

That was pretty simple. However, there is a minor issue. I want to know why a task is paused, much like I’d like to know why an issue is closed as ‘Will not fixed’. I’d like the person pausing it to provide a comment as to why the task has been put on hold. How can I accomplish this in YouTrack? How can I force someone to submit a comment when a state is set to Paused.

Workflow Editor

This is where YouTrack’s workflow editor comes into play. I looked at this tool nearly 2 years ago and I must say, there have been some major improvements. However what really shocked me was how simple it was to get up to speed. In less than 15 minutes I had downloaded it, created a custom rule and had it working on my project.

The workflow editor is based on MPS or Meta Programming System. If you’re not familiar with this, it is an extremely powerful Open Source tool from us that allows you to create and extend languages. But it’s not limited to only creating a DSL. It also provides you with the means to create editors, complete with Intellisense, Code Analysis and Debuggers. In fact, YouTrack itself is based on a language called WEBR which is developed on MPS.

The good news of course is that you do not need to know anything about MPS to work with Workflows in YouTrack. There’s already a packaged-up, self-contained editor that provides you with everything you need.

Let’s see how we can use this to add some spice to YouTrack.

Scenario: Requiring a comment when changing a state

The problem we are going to tackle is the one mentioned previously: we want the user to fill out a comment when changing the state of an issue. Since there’s no specific workflow built for this, we need to create one. As such, we first download the Workflow editor. You can do this from YouTrack itself, under the Workflow tab

Once download (it works on any platform as it’s based on Java), open it up. The first time you run it, it will display a hint box that the connection settings to the server need to be defined. You DO NOT need to have root permissions to the server to define workflow. You DO NEED however Administrative privileges on the Projects you want to use your workflows with.

1. Define these settings by clicking on the Connection Settings link. You can always change them later by clicking on the Workflow | Connection Strings menu entry.

Once you verify the connection, you are ready to start defining some workflows. On first run, it will prompt you to download existing workflows from the server. If it does not or this is a second run, click on Workflow | Download Workflows from Server. A good reason to do this is that you will get all predefined workflows in YouTrack which serve as great examples for defining new ones.

If all goes well, you should end up with your Workflow explorer having some entries:

2. Define a new workflow

The next step is to define a new Workflow. Every workflow we define is imported in to YouTrack as its own package. As such, a workflow allows us to group several specific rules together. We’ll get into what rules are in a moment.

To create a new Worfklow click on the Create Workflow icon on the toolbar

Give it a name. I’ve followed the convention to use server_name-project_name-description_of_workflow:

Next step is to decide what type of workflow this is:

In this scenario, we’re going to create a Stateless Rule (we’ll cover the other two options in a future blog post). A Stateless Rule means it doesn’t hold any state. In our case, we want to make sure every time a field holds a specific value (Paused) a comment is required. We’re not interested at this point, what the previous value of the field was, so we won’t need to hold state.

Here’s where it gets interesting. When you create the rule, a new editor is opened up. This is the rules editor. It’s a complete IDE (the power of MPS at work) that provides us with all the goodies such as syntax highlighting, code analysis and other things. First thing it prompts us for is a name.

We’re going to call this rule Changing to pause requires comments. Note that for the rule name, spaces are allowed:

The next step is to define the actual rule. Now as a newbie, it would kind of hard to know what can be done here. Fortunately, when we downloaded all the workflows, these all serve as examples. Added to that, we have Intellisense available too. Placing our cursor on the <issue…> and hitting Ctrl+Space, we get:

This has been filtered down to everything starting with ‘S’ because we’re interested in dealing with a State change. We can see that we have the State entry available. If you’re wondering where these values come from, much like YouTrack Search Facility, it provides us with information not only on fields, but also on values of these fields. Entering State now displays:

and we can select the becomes entry, which as the hint (albeit incorrectly) says, is an event that occurs when the value changes to a specific value. Unsurprisingly, becomes takes a value:

which is the new value of the field. In our case this would be ‘Paused’. A couple of powerful things to notice before we continue. If we enter ‘Paused’ prior to creating that as a value on the server, the workflow editor will warn us that this value does not exist. It will even provide us with an Intention (in ReSharper known as QuickFix) to create this value for all projects:

The next part is to define the actual action we want to take place when this condition is met. Here we can use the assert statement

filling in the condition and the message appropriately. In our case it would be

With that, we’re pretty much done defining our rule. The only thing left to do is push it to the server to make it available and then use it in the project.

3. To upload the workflow with the server, we can select the Workflow | Upload Workflows to Server menu entry

waiting for the upload to finish

4. Once that is complete, we then go back to YouTrack and attach the newly created workflow to the project. We select again the Workflow tab on the corresponding project and click on Attach Workflow

If the uploading in Step 3 succeeded, we should now see our new Workflow in the Dialog box.

We’re done. Now when we change the state of an issue to Paused, it should display a message prompting for a comment

Summary

In this post I gave you an introduction to the YouTrack Workflow editor and we saw how to create a simple rule, upload it to YouTrack and put it in action. What’s more, the editor is based on MPS and hopefully you have seen the power that MPS can offer us. In the next posts I’ll show you how to create more complex workflows that involve scheduling and state machines.

The Typical Developer Workflow

* Thanks to @gregyoung for enriching me with whatthecommit.com

In general, as developers we hate uninteresting tasks such as managing issues, so the less time and effort we spend in tracking bugs and features the better. The worse case scenario is the one outlined in the previous workflow, i.e. work on a bug, comment the fix in source control and then separately manage the issue in an issue tracker. Ideally, we’d like to only have to indicate what we’ve worked on and how it’s related to a check-in once! And fortunately with YouTrack, we can. However, YouTrack goes one step further. It actually allows us to control issues from our source control. Let’s see how this plays out when it comes to using GitHub.

 

In essence we have two options when it comes to integration GitHub:

• Directly via GitHub Service Hooks.
• Use TeamCity as the gateway, which in itself offers other advantages (opening it up to other VCS’s too).

 

We’ll cover each of these in detail.

YouTrack and GitHub Service Hooks

Earlier this year, GitHub provided official support for YouTrack hooks, allowing for tight integration between the two systems. This makes it extremely easy to set up YouTrack for issue management.

Assuming we have a project already set up on YouTrack and GitHub:

1.  Click on the project in GitHub and select Admin

2. Select the Service Hooks from the left-hand side menu

3. At the very bottom of the list of Service Hooks, select YouTrack

4. Enter the following information in the form provided

A few things to note here:

• Base Url is the url of your YouTrack server, which is independent of the actual project.
• Committers is the group in YouTrack that has permission to commit to source code for the particular.
• Username should be a user on YouTrack with Server Admin rights [In an upcoming release this will change to only require Project Admin rights].

 

5. Switching over to the YouTrack side, the only thing required is the to create the Committers group and add the correct users to it. This step isn’t required but it’s good practice to limit the users that can update an issue to those associated with the project.

6. A last important step (which is performed once only)  is to make sure the REST interface is activated on YouTrack (via the Administration Settings)

Putting it to work – Hello YouTrack Commands

Now that we have the two systems linked up, how do we actually get this to work? If you’re not familiar with YouTrack, you might not know about an amazing feature it has called commands.

When most people look at YouTrack, all the see is just another web application with links to click on. However, the true power of YouTrack is in it’s support for commands, which is basically a way of sending it different pieces of text that it understands. This is normally done using the Invoke Command window (Alt+Ctrl+J…yes YouTrack is VERY keyboard friendly):

We start typing text and YouTrack offers us completion and tries to figure out what we’re trying to do. It’s smart enough that it doesn’t need us to spell things out, i.e. instead of having to type “state: fixed assignee: hhariri”, we can just type “fixed hhariri” and it figures out the rest:

It even remembers recent commands we’ve applied to offer the same combinations to us on the next input.

Now if we take this concept of commands and combine that with the usually useless commit messages we can actually come up with something useful! We can use the commit messages to send YouTrack commands (in fact, with YouTrackSharp I’ve started implementing PowerShell commandlets to allow console support for YouTrack too). As such, from our console our Git GUI we can do the following:

What we’ve done here is provide a command as commit message. We’ve identified the issue we’re going to apply the command to (issue Id prefixed with #) and followed it by the command Fixed.

Once we do this and push it to GitHub, the Service Hooks in GitHub will now supply this information to YouTrack, which in turn parses the command and applies it to the issue:

Notice a few things here:

• The issue’s history has been updated with the date/time it was resolved along with a comment saying it was emitted via commit by hhariri.
• The issue has been actually marked as Fixed.
• The Username is clickable. It has correctly identified the username that checked in and mapped that to the YouTrack user. How does it do know that? Simple. It’s based on the email address. That’s why it’s important to have the correct email address associated with both account.

Multiple Issues

YouTrack also supports multiple issues being updated via the commit message. In order to do this via the commit message, each issue should be on it’s own line (i.e. when using the console, don’t provide the –m option with the commit and have Git prompt you with an editor to input comments).

Also it is important to note that the commit messages are not limited to just the “Fixed” command, but other commands can also be added such as tagging an issue, etc. (comments currently is not supported).

Integrating GitHub (or any VCS) with YouTrack via TeamCity

The second option for integration between YouTrack and GitHub is using TeamCity as the gateway. The advantage to this mechanism (apart from using TeamCity!) is that it now opens the door to more VCS options, including Subersion, Perforce, Git, Hg and all VCS’s that TeamCity supports.

The steps to integrate YouTrack and TeamCity are pretty straightforward:

1. Click on YouTrack Administration and select TeamCity Integration

2. Select to Enable TeamCity Integration and click on the Add TeamCity Server link

Enter the information as described in the dialog box and click Save.

3. Once the server is set up, we now need to define the mappings between TeamCity and YouTrack projects. For that, we click on the define mapping link:

We need to define pretty much all the values in the dialog box (which are self-descriptive).

In addition to the minimum required settings, we can also define restrictions on which groups have access to viewing issues via the Permissions tab, as well define a default command to be set on issues affected by failed builds:

4. In order to get the User Mapping, YouTrack like before uses the Email address. As such, we need to make sure that our VCS is configured to map to email. This is done on the TeamCity side under My Settings and Tools which is located under the Username menu [Note we have now switched to TeamCity]:

We edit the corresponding settings and set the Git roots to use email:

5. That’s all that is needed in order to get VCS commands working via TeamCity acting as gateway. This will now provide us information and output like the following in YouTrack when sending a fixed command via a commit message:

With this, a new Tab appears on YouTrack named TeamCity which contains information about the commit being made along with a link to the username.

We could in essence stop right here. The next step however is to go full force and get some of the added benefits of integrating TeamCity and YouTrack, this time from TeamCity’s side.

6. Under TeamCity Adminsitration click on Server Configuration and then on the Issue Tracker tab

7. We now need to create a new connection by clicking on Create New Connection, and entering the following information:

Once we test the connection we can click Create and we’re done. From this point on, we can click on Changes and have drill-down information on issues, link directly to them, etc.

Summary

As we can see, there are two ways to integrate YouTrack and TeamCity. The former requires a little bit less of a setup but is restricted to GitHub (currently). The latter gives us the full benefit of having a tight integration between TeamCity and YouTrack and opens up the door to using any VCS that TeamCity supports.

Most importantly however, the purpose of all this is to streamline the process, making issue management simple, non-intrusive and easy to work with.

 

[Note: If you’re an OSS project lead, note that TeamCity and YouTrack Integration are already setup on Codebetter.com. Ping me if you need help setting up your project details to take advantage of what’s been explained here].

On and off I’ve been working on a .NET library that is a wrapper around YouTrack ReST API’s. YouTrack offers quite a lot of possibilities when it comes to interacting with it. I’ve previously blogged about how we can easily create some HTML 5 graphs using nothing but the ReST API and some jQuery. Of course, we could also take advantage of this API from .NET using merely an HTTP client.

YouTrackSharp

What YouTrackSharp brings to the table is a compact interface to work with YouTrack without worrying about things like cookies, URL’s and other HTTP concerns. It abstracts all that way to provide a simple series of classes to work with YouTrack.

Here’s a sample of a command line app I just wrote to make feature logging easier for ReSharper:

var connection = new Connection(”youtrack.jetbrains.net”);

connection.Authenticate(”username”, “password”);

var issueManagement = new IssueManagement(connection);

var issue = new Issue
{
Assignee = “ReSharperProjectManager”,
Summary = summary,
Description = description,
ProjectShortName = “RSRP”,
Type = “Feature”
};

issueManagement.CreateIssue(issue);

Console.WriteLine(”Feature request logged”);

Currently it allows you to Create Issues, Upload Attachments, Get Issues, Apply Commands to issues as well as a bunch of tasks on Projects. I’m adding features as and when I can, so if there’s something you’d like, log it here.

How to use it

YouTrackSharp is available as a NuGet package and source code is available on GitHub. To use it, just do:

install-package YouTrackSharp

You first need to create a Connection object (providing host) and then either a IssueManagement or ProjectManagement based on what you need to do. The classes are simple and the methods should be self explanatory. The project also comes with tests using MSpec which describe many scenarios. If you have any questions, shout!

Ruby

If you are a Ruby developer, know that Anna Zhdan, a colleague at JetBrains, has also started working on a Ruby library for YouTrack, which is available on GitHub

On the 5th May, in collaboration with our partners Pluralsight, we will be doing a webcast on Agile environments:

 

- What exactly is an Agile environment

- Best practices for setting up environments with TeamCity, YouTrack and an OSS stack

 

This webcast is completely free and open to all. Please check out Pluralsight’s website for more information and registration information.

On Tuesday I’ll be giving a webinar (in Spanish) on how to setup an environment with TeamCity, YouTrack and your favorite OSS tools and frameworks.

 

Things we’ll see:

 

TeamCity: Overview and benefits

YouTrack: Mouseless Web Issue Tracking

Introduction to Distributed Version Control Systems and benefits over Centralized

Creating Continuous Integration Processes with TeamCity and OSS stacks

Integration with Visual Studio and other IDE’s

 

The webinar will be roughly 2 hours and it will be mostly demo-centric.

It is a completely free event. If you’d like to attend, please register here

A few days ago, a customer of ours asked me if it would be possible to visualize statistics in graphs in our Bug Tracker YouTrack. Answer is Yes. Since YouTrack offers a “ReSTful” API, you can obtain pretty much any kind of information you want from it and once you have this information, you can then display it however you wish, be it a table or a graph.

 

Let’s see how.

 

What we’ll be using…

One of the great benefits of jQuery is the rich ecosystem it offers. There’s a plug-in for pretty much everything you need, even for displaying graphs. In fact there are quite a few. We’ll be using jQuery Visualize. We’ll also be using jQuery (I’m using 1.4.4 but should work with older version) and jQueryUI, which is needed by jQuery Visualize. Finally we’ll also need jQuery Templates (I’ll explain why later on).

Don’t worry about downloading each individual file. Everything you’ll need is included in the demo code attached to this post.

Getting the information from YouTrack

For this demo, what we want to do is create a chart containing Issue counts for different projects. In particular, we are interested in Open, Fixed and Duplicate issues for ReSharper, dotCover and dotTrace:

In order to get this information from YouTrack we have to make a request to count the number of issues based on filters, i.e  ReSharper + Open, ReSharper + Fixed, etc.*. The URL for this would be:

http://youtrack.host.com/rest/issue/count?filter=project:ReSharper%20state:Fixed

which is nothing other than a URL encoded version of a search expression we can enter directly into YouTrack’s web interface,but to the rest API. We therefore need to send requests from our web page to YouTrack to obtain this information. The way we can do this is with Ajax and JSONP which YouTrack supports. Using jQuery.ajax, our code would look like this:

Problem is, this wouldn’t work, or at least, not always. When requesting a count of issues by YouTrack, the response is not immediate. YouTrack will free the request and will spin off to calculate the count. Once it’s complete it will then store the information in the cache. Next time a request is made, the value from the cache will be returned. What this means to us is that if we fire off a request, if it’s a cache miss, then we will get back a –1 instead of the actual count. We would therefore need to send a new request, until we get a value greater or equal to 0. This is not complicated to do with JavaScript and in particular with jQuery. It merely consists of polling for a result. But like all things jQuery, before you re-invent the wheel, check to see if there’s already a wheel and it turns to your liking, something which in this case does. This alternative to $.ajax allows us to poll servers and only process the result if a condition is met. As such, our previous code would now look like this:

 

(the polling interval can be set for the calls. Here we’re using the default value).

In terms of requesting information from YouTrack, that’s all there is to it. What we need to do now is repeat the process for each project and status type and store the value.

[* Currently YouTrack does not support grouping so multiple requests will have to be made. This feature is planned however]

Representing the information as a table using jQuery Templates

We want to do two things with the results, represent them as an HTML table and display them as a graph. The data retrieved from the server is given to us as an array of objects (something we did in the code ourselves), where each object has a one property indicating the Project and three additional properties with the values of each status:

 

We would now need to iterate through this array and generate a table from it. Instead of doing this in an ugly way by mixing tags with data, we can take advantage of jQuery templates (if you are not familiar with templates, you can think of them as a view engine for jQuery). What we do is define a template and then make a call to a function that replaces placeholders with our data. If the data we provide this function is an array, it will repeat it for each entry.

The code first creates the template for the markup we want to generate, which are rows of a table. It then calls the template function to create a compiled version of the template which will then be passed in to the tmpl function along with the data (the series variable). The call to appendTo is a jQuery method which adds the contents of the object it’s called on to the item passed in to the selector (in this case #rows). 

In the body section of our page, we can then define the rest of the table, which includes the header and the tag for the table body:

Creating the Graph

So far we have retrieved the information from YouTrack and created an HTML table to display it. Our main objective however was to also display this information graphically. That in fact is the easiest part. One reason we are using jQuery Visualize is because it can easily convert a table into a graph (it supports different types of graphs, including lines, pies, etc.). All we need to do is call visualize on a table.

That’s all there is to it. Once we put all the pieces together, we will end up with the following page:

This chart works in all browsers I’ve tested (IE 9, Opera, Firefox and Chrome)

Summary

The complete code for requesting information from YouTrack and generating the Graphs is available on my GitHub Blog repository. Once you examine it, you’ll see that it’s very few lines of code, thanks to the rich ecosystem around jQuery. I’m sure it can even be improved further, since I am by far a jQuery expert and can also be made a bit more generic to allow for different statistics to be obtained without change to the source.

I’m currently working on YouTrackSharp which is a wrapper for YouTrack requests in C#. So if you’re interested in doing the same thing from C#, you will soon be able to do.

As always, if you have any questions please leave a comment.

Enjoy!