Ticket

For the release planning and tracking of who does what, we use Sourceforge's ticket system. The basic idea is that for each new release, we open up a couple of coarse tickets that describe items what to do (see here for details), then people take them and implement the issues.

Now that is pretty much all there is to say about the basics, the remainder of this page describes the details of a ticket, finally, we add a few notes about how the ticket system is meant to work. All rules here are subject to change if we find that something does not work out.

Fields of a ticket

• Milestone
  Gives the release for which the ticket is scheduled. If a certain ticket is not relevant for the next release, it will usually stay in the backlog.

• Status
  A ticket proceeds through currently four distinct stages:

  • Open
    The ticket has been created, but needs further thinking, clarification, or specification. Open tickets have either not been processed yet, or they are very general in nature, for example vagure ideas, that have to be converted into more specific tickets.
  • ReadyForDev
    The ticket has been thought through and specified to such a degree than any pair of developers should be able to just take the ticket, look at the description, and start working on it.
  • InProgress
    Once a developer/reviewer pair has taken over a ticket, the status changes to InProgress while the design, coding and reviewing is being done
  • Closed
    When the ticket is finished, it is closed.
• Owner, Owner2
  The pair of developers that are working on the ticket. For all states != InProgress, these fields should be empty.
• Type
  The rough type of the task.
  • Bug
    The task is a bug that needs fixing
  • Refactoring
    The task involves changing the code without significant functional changes to the program
  • NewFeature
    The task involves writing a substantial amount of new code that extends the program
  • Spec
    The ticket is not about coding directly, but finding something out. Imagine we want to do a big migration to Spring, then we would not do this in one step, but first figure out how a migration could look like, if Spring does everything we want etc. The output of such a ticket would be mainly further tickets that describe the implementation route.
  • Other
    Nothing to code, but organization work to door anything else that does not fit the other categories. For example, setting up a test system would be of type "other".
• Tags
  are currently not used, but this may well change when the tickets should be categorized further.
• Text body
  The description of a ticket should generally follow the following template:
  • Summary
    In a first section, the problem is briefly explained. Use few sentences, ideally up to three.
  • Acceptance criteria
    What should be the output of the ticket? When is it done? Try to spell it out explicitly to avoid scope creep. If, for example, we want to start using a GUI library, spell out exactly how much should be converted to the new GUI.
  • Notes
    Already available knowledge, various notes, problems that have already been recognized etc. belong into the third section.

How to work with the ticket system

The first transition of a ticket from Open to ReadyForDev usually involves a bit of processing. Mainly fleshing out the text and the metadata, which should also include some reviewing. This processing is currently done by the admins, although this is supposed to change. In particular, we need to

• focus the ticket, so that there is a specific goal that can be reached in a reasonable time frame
• occasionally, do a first survey of the code to get an idea what should/could be done in addition or before this issue can be tackled etc.
• write down everything so that the description alone is sufficient to get started with the ticket.
• Set the correct metadata if required.

When you choose a ticket to work on, tickets that are assigned to the next milestone should have priority. However, it may always happen that none of these fit the situation (for example, none may be suited for introducing a new developer). In such a case, just pick one from the backlog.

When working on a ticket, try to add a summary of each chat as a comment to the ticket. This is a real boon when reviewing (because you do not have to read through a tangled mess of chat log to figure out what you want to review). Also, it helps if the ticket is reassigned, for example because a developer lacks time to finish an issue. In such a case, the new developer can get most of the information from just reading the ticket. If it turns out that the description of the ticket deviates from what the task at hand turns into, you should also update the description.

Ideally, you should name branches and tag commits with the id of the ticket, so that later developers can figure out why a certain commit was done in the way it was done.

... to be continued...