How to make good tickets?

What is a ticket?

Tickets are units of work that we agree upon in the team. We use them to lead our work meetings and communicate our ideas amongst each other.

Therefore:

• tickets should be understandable by all, see below howto.
• tickets should be not be to big or too small; about THREE tickets per personweek is enough
• tickets are often shared between multiple people
• tickets can be moved from one milestone to another so they can be big (so don't duplicate them) but not too big, see below howto.
• tickets can have links to wiki pages or other tickets. Please use that in particular if you work from a Design
• tickets have a discussion option, plz use that to discuss actions and results while the ticket progresses.
• if you have many small todos, please put them in ONE extra ticket so we can still discuss them during work meeting.

What makes a good ticket?

For a good ticket you can easily answer the following questions:

When the ticket is new:

• Motivation: Why or for whom do we have this ticket? For example: for LifeLines.
• Scope: What is the expected output to close this ticket? For example: wiki page, Excel file, Working demo, Unit test, etc.

When the ticket is worked upon:

• Actions: What are we planning to do to produce the expected output? For example: interview, program, design, statistical test, etc.
• Evaluation: What are the criteria of succes on which we (or the customer) decides the outcome is good enough? For example: evaluated by person X, test-case passed, presented at meeting X.

Please use the discussion mechanism to have discussions on the actions. It is like a forum :-)

Size of tickets?

If you can't easily answer the questions above for your ticket is probably too big!

In that case it needs to be in a chain of smaller tickets, and the first ticket is than to answer all these questions. For example: Design a user interface for LIMS is way too big. Expected evolution of your tickets in such case:

• Ticket 1: Create a mock-up for lab data-entry based on protocols. Expected output is a wiki page with the mock-up that has been evaluated with Morris and/or team members.
• Ticket 2: Implement user interface for lab data-entry based on protocols. Expected output is a working demo of (link to output of ticket 1 here) + manual that has been evaluated with Morris and/or team members.
• Ticket 3: User test interface for lab-entry. Expected output is a log on where the user had trouble. Typical result may be that Ticket 2 is reopened for improvement..

Implicit in above is: the code is commited to SVN and there is a manual on the wiki of your component.

What ticket type to use?

Currently we have four flavors of tickets. For each of them examples are shown:

todo	A todo is a unit of work that does not result in commits to SVN but instead in a wiki page, Excel document, a presentation and so on. So what you need to do is describe this expected output. Example ticket: Comparison of imputation methods Beagle, Impute and MACH component: gwas Why or for whom? For medgen and bbmri we want to compare imputation methods Beagle, Impute and MACH. Expected output? An Excel document that describes a comparable percentage correctly estimated SNPs. Action plan? Take existing genotype data from 1M arrays and split the data randomly in two. The first half we input into the impute methods. Then we compare the SNPs called with those actually called on the array and calculate percentage correctly estimated SNPs. Evaluation plan? We will feed back results to Lude and Cisca's teams to evaluate outcomes and if necessary propose further testing.
enhancement	An enhancement is working on a new set of features in our software. In this case we EXPECT that there has already been a ticket that defines this enhancement. In these cases the ticket is simple: Example ticket: Implement use case: SearchQTLprofiles component: xqtl Implement the enhancement as described in http://www.xgap.org/wiki/XqtlReview#Usecase1.SearchQTLprofiles
defect	A defect is a known error in our code base. In this case the ticket MUST describe what you need to do to reproduce the defect and you MUST create a test that shows the problem. If possible you will first create a UnitTest? that shows the bug so that it can never come back without us knowing. Example ticket: Fix JPA if primary key is not named 'id' component: molgenis Why or for whom? This ticket is a showstopper for ticket xyz. Expected output? 1. checkout molgenis and molgenis_test 2. add a new <entity> with a <field name="myid" type="autoid"/> 2. generate code 3. run build.xml without errors Action plan? Correct generators to get rid of compile errors. Evaluation method? UnitTest. If it is a user interface error you have to describe the procedure here.
test	A test is a special ticket to move the todo of 'testing' an enhancement or bugfix to others in the team. Usually it only refers to the other ticket where the actual bug/enhancement is described. Also newly reported bugs may first need a test case before the tickets can be changed into a bugfix. Example ticket: Why or for whom? We got a report stating that the REST api doesn't work from Java client Expected output? Have a test case that uses the REST api and succeeded/fails Action plan? Create a small REST client Evaluation method? Feed back to the bug reporter what we found and what actions we will take.