How many bugs can you keep track of in your head at once? If you are anything like me, that number is somewhere in the single digit range. This is why issue tracking is a very important tool that every programmer should be using now. There are tons of free issue tracking programs like Mantis, Bugzilla, or even web based applications like Lighthouse. There is no excuse to put it off any longer if you aren’t already doing it. The reason it is important to use issue tracking on every project is that you will be more likely to produce a better product by fixing bugs before you add new features. Tracking your issues also allows your clients to see what you are doing on their projects and allows them to have a better understanding of what their deadline and progress expectations should be.
Frankly I think simplicity is best for issue tracking and Lighthouse is the tool I use to handle all of my issue tracking for every project I work on. It is a very simple, powerful and beautiful issue tracker that allows for third party integration via its API. This is great because you can commit files and the changes will be attached to your tickets, like commits from GitHub or Beanstalk.
Sample Project
In this post I will walk though the basics of setting up a simple issue tracker for a fictional new client, “Inmate Penpals, Inc.” The company in this example bought their website as a script for $999 and it is simply broken. The company described in their job posting a very long list of features that were broken, or bugs that needed to be fixed. Sounds great right? Why bother setting up an issue tracker?The client already made a list!
90% of clients will not know the full extent of their issues beforehand, so treat any project description as a synopsis of their issues
The first thing that you need to do is convince the client that they need an issue tracker, as it will help keep the project on budget and allow them the opportunity to see you making progress on their projects. It won’t cost them a dime to set up a free account over at Lighthouseapp, so that argument should be pretty easy to win!
Step 1:
Set Up a Issue Tracker
First, sign up for a free lighthouseapp account. You have to choose your project url, which in this case will be inmatepenpals.lighthouseapp.com.
Once you have confirmed your email address you can click the link and be taken directly to your project dashboard, which is totally empty right now. Next, click “Create a New Project” to set up your first project.
Create a new Lighthouse project
You have to fill out some details about your project, mainly the project name and description. The important thing on this page are the options for “Public Project“, “Private Project“, and “Open Source Project“. For most client work, you are going to want to choose “Private Project” because you don’t want to share your troubles with the world, especially considering that sensitive information may be stored on the issue tracker.
Invite users to Project
Next you will want to invite your client to the tracker, or have them invite you if they set it up. On this screen you can set read & write permissions for other users or invite people via email. Since I don’t want to add another user right now I will move on to the next section, defining milestones.
Step 2:
Define Project Milestones
Milestones are important because they allow you to set a date for certain bugs or features to be fixed or implemented by. For this project I will create two milestones, one for the expected due date of the project, and one for any future features or enhancements that are beyond the scope of the project deadline. Every ticket represents an issue, and every issue belongs to a single milestone. This way you can easily prioritize the due dates of your tickets and track their progress.
New Projects appear on the right hand side of the screenProjects
The milestones tab is located on the top menu
To create a milestone, we first have to make sure we are in the project screen for our new project. From the dashboard, you can see all of the projects listed on the right hand side of the interface. Since we only have one project, it should be pretty easy to spot. Click the project name and you will be taken to the project overview page.From the project overview screen, you will see a menu that says “Milestones“. Click on this to go to the milestone edit screen.
Create a New Milestone
From the “Milestone” screen you can view, add, edit or delete your project milestones. To create a milestone, you simply click the “Create Milestone” menu link.
Set the milestone title, due date, and description
We want to add milestones for our first due date, which I have set to Dec 30, 2010. The focus and goals for this milestone are to fix all of the major bugs. Once your save the milestone, I want to click “New Milestone” again to create a second milestone.
Set a Future milestone, with no due date
In most projects, there are features that would be nice to have but really aren’t important enough to get done on your current milestone. In order to avoid scope creep, it is important to put these tickets into a separate milestone. You can always move tickets in or out of the milestone, in this case called “Future“, into a milestone with a due date.
Step 3:
Working with tickets
Milestone’s are all well and good, but “Tickets” are the real meat of the issue tracking experience. A ticket can represent anything from a large feature request, a small database bug, or something even as small as a typo. The ticket system in Lighthouseapp is really exceptional. You can add attachments, assign tickets to specific users, and even integrate 3rd party changesets (i.e. commits) to update directly on the tickets! When combined with versioning from GitHub or Beanstalkapp, this is a powerful way to track the code as it changes over time.
The client has submitted a job description, which describes what the client wants accomplished overall. Our job is to parse this out into separate tickets. This might be a bit difficult at first as we come to terms with the scope of the project, but it will git much easier to refine after we enter everything in.
Our site is completely malfunctioned. The email doesn’t work when the user sends a note to an inmate. There is a display bug on the homepage when you hover your mouse over the “contact us” 3d button that causes the button to go away. Our server seems really slow and I want all of this fixed. On the homepage only 10 inmates pictures are supposed to show but instead the whole database of prisoners loads. We would also like to have a rotating slideshow that makes the entire page change colors during the holidays. Thanks! -InmatePenpals CEO
Wow, that wasn’t the worst job post I ever saw, but it certainly needs to be broken down a bit further. We are going to start creating “tickets” for each issue.
The new ticket button is available almost anywhere in the project overview
Make sure that you are somewhere in the “Project Overview” section of the tracker. From almost anywhere in here you can click the “Create a New Ticket” button.
I usually start out making the tickets rather quickly. I will simply copy and paste the problem in the clients own words to describe the ticket.
Enter the ticket title and description
Enter a descriptive title for the ticket. I try an use my best judgement to sum up in my own words the issue at-hand. For description I will usually paste the words of the client and any other info the client has given about the problem. In some cases I may also attach a screenshot of the problem if it is visually demonstrable.
Assign the ticket to a user and milestone
You should also set the ticket to be assigned to yourself, since you will be fixing it. As for milestone, that really depends upon the request the client has made. If it is something from the original job description, I would probably consider that to be part of the project due date, in our case the Alpha Test milestone. On the other hand, if it were a feature request that the client put in two weeks after the project starts, I would probably put that into Future.
Set your tags consistently
Each ticket also has a line for “Tags“. Tags are something that need to be fairly consistent throughout your project and I will tell you why when we create ticket bins to categorize our tickets. Two tags that are very important are “defect” and “enhancement“. I tend to categorize every ticket into one of those two categories. Most bugs are defects and most features that don’t exist or need to be improved are called enhancements. Since the ticket in question relates to email not working, we can assume the it is a “defect“. We can always change this later to “enhancement” if it turns out that email functionality was never implemented in the first place. I also added the tag “email“, but I don’t want to go tag crazy so two tags should be fine in most cases.
The ticket view
The tickets index
I went ahead and created the other tickets while you were reading the previous section. Make sure to tag your bugs as defect and your feature requests as enhancement. Make sure to go eover each ticket with your client to make sure you are both on the same page, and also to further clarify the ticket. Posting an update to a ticket is a simple as adding a comment. You can change the ticket title, upload screenshots, change tags, or change anything else about the ticket from the “Ticket Detail” screen. Once you have entered all the initial tickets, you can start organizing them into “Ticket Bins“, which is a fancy way of saying a group of tickets.
Step 4:
Grouping and sorting tickets with Ticket Bins
I like to use Ticket Bins to group my tickets into separate categories. I make one ticket bind for defects, and another one for enhancements. Lighthouseapp already provides some ticket bins by default, under “Shared Ticket Bins” on the right hand side of the screen. These are “Open Tickets“, “Resolved Tickets“, and “This week’s tickets“. Each ticket bin has a number next to it showing how many tickets are in that bin. A ticket can be in an unlimited number of bins.
I always create two new ticket bins with every new project. These bins will be called “Open Defects“, and “Open Enhancements“.
Click the "Tickets" menu link
To create a custom search bin, aka ticket bin, you must first be on the main tickets index screen. To get here quickly you can click the “Tickets” menu item.
We have to enter our criteria under "Find Tickets"
We have to set the search criteria for our ticket bins. In fact we can save any search as a ticket bin. Click here for a list of all searchable attributes.
Add in tagged:defecttagged
To get a list of all open defect tickets that I am responsible for, I need to enter the following onto the “Find Tickets” line.
responsible:me state:open tagged:defect
The ticket search shows only tickets tagged with defect
Now only tickets that I previously tagged as “defect” will appear in the list. To save the bin you must click on “Save as Search Bin“.
Give the search bin a name “Open Defects“. I also repeated these steps for our “Open Enhancements” ticket bin.
New bins will now appear on the right hand side of the screen
The new search bins will now appear in the list of “Shared Ticket Bins“. This is a very convenient way to organize your tickets by almost any criteria you can think of!
Step 5:
Integrate Version Control From GitHub or Beanstalkapp
The best part of all of this is the fact that you can integrate your commit messages from GitHub, Beanstalkapp, or several other providers. It just so happens that I set up a project for this over at Beanstalkapp, but setting it up via GitHub is quite similar.
You create an API token for your username
To create an “API token“, you must click on your username, and you will see on the right hand side of the screen a select list. Choose the current account to create an API token for this specific tracker account, or select “All Accounts” to generate an API token that can be used on all tracker accounts associated with your the logged in user.
Set API key permissions
For the purposes of our example, I chose to create an “API Token” for the current account, labeled Beanstalkapp since that is who I am giving the key to. I also chose to gave the key “Full Access” instead of “Read only access“.
Your new API token will appear on the right hand side
Once in Beanstalk or GitHub, you will need to connect your repository to Lighthouse. Here is a complete screencast for integrating Lighthouse with GitHub.
Integration in Beanstalkapp
Activate Lighthouse Integration
Add Lighthouse Tracker URL
Paste your API token into the box
Select the project from the list
Activate the Integration
Once inside your Beanstalk repository dashboard interface, click the “Integration” menu link. You will see a list of services on the left that you can hook into with Beanstalk. Choose “Lighthouse” and click the “Activate” button. All you have to do in the next few forms is paste in your Lighthouse URL, paste in your API, select your active project and you are ready to Activate the integration.
Once we are hooked in via Beanstalk or GitHub, you can add things in your commit messages that will post directly to tickets you create in Lighthouse.
Make some changes and commit your files
Now when you commit your files, you can add in special tags to tell Beanstalk to push your changesets to Lighthouse.
![Add the ticket number number in brackets ex [#1]](http://www.jblotus.com/wp-content/uploads/2010/12/ticketnumber1-550x327.jpg "ticketnumber")
Add the ticket number number in brackets ex [#1
To assign a commit to a specific ticket do this:
this is my commit message [#1] //#1 is the ticket number
To close a ticket do this:
this is my commit message [#1 state:resolved] //#1 is the ticket number
All of the keywords go inside square brackets []. I usually don’t close tickets directly from a commit, and I find that assigning a commit to a specific ticket is usually good enough. You can do some pretty crazy things with Beanstalk such as automatic deployment, just from a simple commit message. Here is a complete list of Lighthouse keywords.
New Changesets show up in Lighthouse
Now if you look at the project overview in Lighthouse, you will see our newest changeset and the associated commit message.
The changeset and update details as a commentchangeset
You will see the newest changeset and commit message applied as a comment to the ticket. You can easily view the changes made by clicking on the corresponding link.
Step 6:
Ticket Management
At this point you might want to mark a ticket as “Resolved” if the issue described has been solved. The different ways you can mark a ticket’s status are:
- New - New ticket that has not been worked on. Use this when you first create a ticket.
- Open - A ticket is currently being worked on
- Resolved - A issue has been resolved successfully.
- Hold - Valid issues that can’t be resolved or that aren’t worth resolving.
- Invalid – Issues that are poorly formed, already working, or generally not bugs or feature requests.
How you use these states will be largely up to you, but try not to use “Resolved” in cases where “Hold” or “Invalid” might be more appropriate, such as when you can’t reproduce a bug, or the ticket did not describe a bug but rather incorrect usage.
Summary
Issue tracking should be part of the flow of every programmer for any serious project. Lighthouse is a great choice for the job and they offer a free account, so you have no excuse not to give them a try! So what are you waiting for, get organized today!
