OverviewTeaching: 15 min
Exercises: 10 minQuestions
How can I keep track of what needs to be done?Objectives
Describe what sorts of things should be recorded in an issue-tracking system.
Describe what goes into a well-written issue.
Explain how issue-tracking systems can be used to implement workflows.
Explain how issue-tracking systems can be used to focus attention where it’s needed.
- Issue-tracking tools are often called bug trackers
- Well-organized teams use them as a shared to-do list to manage everything
- “Version control tells us where we’ve been; issue tracking tells us where we’re going.”
- Can be used to:
- Request, plan, and discuss new features
- Describe bugs, and solicit/collect bug reports from community
- Dump ideas for future reference
- Every task is recorded as a separate ticket
- Unique ID
- One-line summary to aid browsing
- Status (sometimes organized by stages of grief)
- Owner (i.e., who’s responsible)
- Full description that may include screenshots, error messages, etc.
- History: who created it when, how it has been modified
- Threaded discussion
ID: 1278 Created-By: mummy Owned-By: wolfman State: assigned Summary: Message file reader crashes on accented characters Description: 1. Create a text file called 'accent.msg' containing the message "Pümpernickel" (with an umlaut over the 'u'). 2. Run 'python mindcontrol.py --all --message accent.msg' Program crashes with the message "No encoding for  on line 1 of 'accent.msg'". ( shows where a solid black box appears in the output instead of a printable character.)
- More sophisticated systems allow people to:
- Record dependencies between tickets
- Estimate how long work will take
- Record how long work actually took
- Can be used to make the development lifecycle explicit
- I.e., only allow certain state transitions
- And notify interested parties of state transitions
- Don’t worry about any of this until people are actually filing issues
- Key utility: prioritization
- What has to be done right now?
- What should be done soon?
- What can safely be left until later?
- Criteria for decision:
- How much do we need this?
- How long will it take?
- Key utility: documenting your team’s work
- Whenever you start working on a new task/feature/bugfix, open a PR early in the process with a description of the in-progress work and links to any relevant tickets.
- Make it clear if and when the PR is ready for intermediate or final review. Use of status tags (such as In Progress and Ready for Review) is encouraged.
- Think of the issue tracker as a shared lab notebook. It contains a full record of work done, along with relevant discussion.
- Everyone can see what everyone else is up to.
What’s On Your List?
- What are the top 3 items on your project’s to-do list?
- How sure are you that your collaborators and users would agree with your selection?
What’s Your Lifecycle?
- What states can your project’s issues be in?
- What state transitions are allowed? (“Any to any” is a common and acceptable answer.)
- Who decides when an issue can move from one state to another?
An issue-tracking system is a shared to-do list for a project.
Every issue has a few mandatory fields to help with searching, and free-form text for details.
Every issue is in a particular state.
A project can define a workflow by specifying who can change tickets’ states when.
Use tickets to prioritize work: what needs be done now, what can be deferred until later.