Issue tracking and team workflow

Requests for ridgeline-tools arrive from everywhere. Kai mentions a roast log idea over coffee. Anita sends a text about a wrong total. Mei writes a sticky note about the loyalty receipts and puts it on the office monitor, where it falls behind the desk. Theo tells Jordan about a shipping report, and Jordan tells Sam, who remembers it slightly differently. Some requests are done twice, some never, and nobody can say what the team is working on this week. The code is in good shape, thanks to Git and reviews; the work around the code is not.

This lesson explains how teams track work with issues, how to write a bug report someone can act on, how labels, priorities and milestones organize issues, how commits and pull requests link to them, how boards and limits on work in progress keep work flowing, how to decide what to do next, and the team habits that make all of this light rather than bureaucratic.

Issues

An issue, also called a ticket, is a record of one piece of work: a bug to fix, a feature to add, a question to answer or a task to do. Hosting services include an issue tracker alongside each repository, and teams also use dedicated tools such as Jira or Linear. Each issue gets a number, such as #21, a title, a description, a discussion thread, a status of open or closed, and optional labels, an assignee and a milestone. The number is how everyone refers to the work, in conversation, in commits and in pull requests.

Issues replace the sticky notes and text messages with one shared list. Anyone on the team can see what has been asked for, who is working on what and what was decided. The discussion stays attached to the work, so when Sam picks up the shipping report in a month, Theo's original request, Jordan's questions and Theo's answers are all in one place. For Ridgeline, Rosa decides that every request, from anyone, becomes an issue; staff who do not use the tracker can send requests to Jordan, who files them.

Writing an issue someone can act on

A good issue gives the person who picks it up everything they need without a conversation. Its title is short and specific: Daily total wrong when a sale is refunded, not Totals broken. A bug report says what happened, what should have happened, the exact steps to make it happen again, and the version or environment, with any error message pasted as text. A feature request describes the problem from the user's point of view and why it matters, rather than prescribing a solution, and says how to tell when it is done.

Title: Daily total wrong when a sale is refunded

What happened
`ridgeline report --day 2026-10-14` shows a total of 1,286.45.

What should happen
The till's end-of-day slip shows 1,267.95. The difference, 18.50,
is one bag of Sunrise Blend that was refunded at 15:40.

Steps to reproduce
1. Use the attached sales export for 14 October (sales-2026-10-14.csv).
2. Run ridgeline report --day 2026-10-14.
3. Compare with the slip (photo attached).

Version: ridgeline-tools 0.4.0 on the office computer
Reported by: Anita

Steps to reproduce are the most valuable part of a bug report. A bug that can be reproduced can be fixed and then tested; one that cannot is a guessing game. Repositories often provide issue templates, such as a bug report form with these headings, so reporters fill in the right information. When you receive a vague issue, ask the questions in the issue thread, so the answers are recorded for whoever works on it.

Labels, priorities and milestones

Labels classify issues so lists can be filtered. Most teams use a small set: a type, such as bug, feature, documentation or question; a priority, such as high, medium or low; and an area, such as loyalty, stock or reports. Keep the set small, because a label nobody applies consistently is worse than none. A milestone groups the issues planned for a release or a period, such as Version 0.5 or November, and shows progress as the share of its issues that are closed. The assignee field says who is doing the work, and an issue should have exactly one.

Triage is the regular habit of going through new issues to label them, set a priority, ask for missing information, close duplicates and decide which ones to do. On a small team it can be ten minutes on Monday morning. Without it, the issue list becomes a pile that nobody trusts.

Linking issues and code

Issues are most useful when the code that resolves them points back to them. Branch names can carry the number, such as fix/33-refund-totals. Commit messages and pull request descriptions mention it, and hosting services turn #33 into a link and show the reference on the issue's page. Certain keywords do more: a pull request whose description includes Fixes #33, Closes #33 or Resolves #33 closes issue 33 automatically when it is merged into the default branch. The issue then records exactly which change fixed it.

import re

KEYWORDS = r'(?:close|closes|closed|fix|fixes|fixed|resolve|resolves|resolved)'

messages = [
    'Fix refund handling in daily totals\n\nFixes #33',
    'Add roast log command (see #27, closes #28)',
    'Update README; refs #21',
]
for m in messages:
    closed = re.findall(KEYWORDS + r'\s+#(\d+)', m, flags=re.IGNORECASE)
    mentioned = re.findall(r'#(\d+)', m)
    print('closes', closed, '| mentions', mentioned)

closes ['33'] | mentions ['33']
closes ['28'] | mentions ['27', '28']
closes [] | mentions ['21']

import re

def closed_issues(text):
    return sorted(int(n) for n in re.findall(r'#(\d+)', text))

print(closed_issues('Fix totals. Fixes #33, see #27'))

Boards and work in progress

A board shows issues as cards in columns that represent stages of work, commonly To do, In progress, In review and Done. Cards move from left to right as work advances, so a glance shows what is waiting, what is being worked on and where things are stuck. Hosting services build boards from issues and pull requests automatically, moving a card to Done when its issue closes. This style of visual workflow comes from kanban, a method first developed for manufacturing.

The most useful rule a board can carry is a limit on work in progress, or WIP limit: a maximum number of cards allowed in a column at once. With two people, In progress might be limited to two cards, one each. The limit stops the common pattern of starting many things and finishing few, and it makes bottlenecks visible: if In review is full, the right next step is to review someone's pull request, not to start something new. Finishing work is worth more than starting it.

def column_counts(cards):
    return {}

def over_limit(cards, limits):
    return []

print(column_counts(CARDS))

Deciding what to do next

There is always more work than time. Priority labels answer most of the question: high-priority bugs that affect the café come first. Within the same priority, older issues usually go first, so nothing waits forever. Some teams weigh value against effort, doing small, valuable items early; others agree on a short list for each week or two, often called a sprint or iteration, and leave everything else for the next planning session. On a small team, a ten-minute conversation on Monday, looking at the board and the high-priority issues, is enough.

def next_up(issues, count):
    return [i['number'] for i in issues][:count]

print(next_up(ISSUES, 3))

Estimates and splitting work

Someone will always ask when a piece of work will be ready, and software estimates are famously unreliable. Two habits make them better. First, split large issues into small ones, each of which can be finished, reviewed and merged in a day or two; the roast log feature becomes separate issues for reading the log, the summary command and the supplier export. Small pieces are easier to estimate, easier to review and deliver value sooner. Second, estimate in rough sizes rather than hours, such as small, medium and large, and compare with similar work the team has finished before, which is a more honest reflection of how uncertain the future is.

Some teams record estimates on issues and compare them with how long the work actually took, which over time shows whether they tend to be optimistic. On a small team, the board itself gives most of this information: if a card has sat in In progress for a week, something is wrong, and the stand-up is the place to ask what is blocking it and whether the issue should be split.

Team rhythm and communication

Teams settle into a rhythm of short, regular meetings. A stand-up is a quick daily check, often fifteen minutes or less, where each person says what they finished, what they are doing next and anything blocking them. A planning session chooses the work for the coming week or two. A retrospective looks back at how the team worked, not what it built, and picks one or two improvements to try. Ridgeline's two developers fold all three into a twenty-minute call on Monday and a short message on Thursday, which is plenty for their size.

Most team communication should be written and attached to the work. Decisions belong in the issue or pull request they concern, not in a private message that the next person cannot see. Questions asked in a shared channel help everyone who has the same question later. Writing well, briefly and with the context a reader needs, is one of the most valuable skills on a software team, and every lesson in this course has practised it: commit messages, pull request descriptions, review comments, READMEs and now issues.

Finally, agree on a definition of done: the checklist that must be true before a card reaches the Done column. For ridgeline-tools it reads: code merged to main through a reviewed pull request, tests added and passing, README and changelog updated where needed, and the person who asked for it told that it is ready. A shared definition prevents the familiar argument about whether something is finished.