Issues and bug reports

An issue is a bug report, an idea or a task, written in the project's issue tracker. Most contributions start with one.

Choosing an issue

Projects mark easy issues with labels such as good first issue or help wanted. Before you start:

1. Read the issue and all its comments. Someone may already be working on it.
2. Leave a comment: "I would like to work on this. My plan is to ..." Some projects want a maintainer to agree first; CONTRIBUTING.md says.
3. Reproduce the problem on your computer before you try to fix it.

A minimal reproduction

def average(numbers):
    return sum(numbers) / len(numbers)


print(average([4, 8, 6]))
print(average([]))

A minimal reproduction is the smallest program that shows the bug. It is the most useful thing a bug report can contain: the maintainer runs it and sees the bug at once, without your whole project. Cut away everything until the bug would disappear if you removed one more line. Press Visualize: the first call works, and the second stops with ZeroDivisionError.

Writing the report

Search the open and closed issues first: your bug may already be reported. Then write:

Title: average() crashes on an empty list

What I did:     called average([])
What I expected: 0, or an error message that explains the problem
What happened:  ZeroDivisionError: division by zero
                (full error message pasted below)
Versions:       mylib 2.1.0, Python 3.12, Windows 11

Minimal reproduction:
    from mylib import average
    print(average([]))

A title that says what is wrong, steps someone else can repeat, and the exact error message, copied, not retyped. "It does not work" gives a maintainer nothing to go on.

The fix

def average(numbers):
    if not numbers:
        return 0
    return sum(numbers) / len(numbers)


assert average([4, 8, 6]) == 6
assert average([]) == 0   # the case from the bug report
print("tests pass")

Should average([]) return 0, or raise a clearer error? That is a design decision, so ask in the issue before you write the fix. Whatever is decided, the fix comes with a test of the case from the report, so the bug cannot come back unnoticed.

Mark lesson complete