Open Source Comes to Campus/Newcomer Tasks/Issue Tracker Cleaning

From OpenHatch wiki
Jump to navigation Jump to search

Overview[edit]

Sometimes communities need help handling all the issues that have been reported. They need to know whether bugs can be reproduced and whether patches/pull requests work as intended. You can help them out by a) reproducing bugs and b) reviewing patches! Along the way, you'll learn a lot about the project.

There are two main types of task you can choose to work on: reproducing bugs, and reviewing patches. Find out how to do each of these tasks below.

Before you begin, you will need to pick a project to contribute to. To do this, try our Finding a Project activity.

Reproducing Bugs[edit]

To find bugs to reproduce, look through the issue tracker. You may want to filter the issues you see so that you're only looking for "new", "unconfirmed" or "open" issues.) Some projects use different terminology, so you may want to ask a mentor to help you figure out what to filter for.) You're looking for issues where a problem has been reported and there are either no comments, or comments requesting that someone verify the bug.

Once you've found a bug report, you'll want to try to reproduce it. You will find yourself in one of three scenarios:

  • There was not enough information in the original report for you to attempt to reproduce it.
  • There was enough information for you to attempt to reproduce the bug, and you reproduced it.
  • There was enough information for you to attempt to reproduce the bug, and but you did not reproduce it.

In each of these cases, you'll want to leave a comment on the issue.

Not Enough Information[edit]

An ideal bug report has a lot of information. That includes:

  • Steps to take to reproduce the problem, including any input (this can be files, text, or instructions such as "click the leftmost button"
  • What they expected to happen
  • What actually happened, including the text of any unexpected output such as error messages
  • Software and operating system versions

If you are having trouble carrying out the steps to reproduce a bug, you should ask a mentor or member of the community whether they can supply the missing information. For instance, perhaps the bug reporter references a part of the project you can't find. It may be, though, that the reporter did not provide enough information for anyone to attempt to reproduce the bug.

In this case, you can help everyone out by identifying the missing information and leaving a comment asking the reporter to provide that information. For instance, you might write:

I'm trying to reproduce this bug, but it's not clear to me what you did leading up to the problem. Which input type seems to cause the problem?

or

Thanks for reporting this bug! Can you tell us which version of the project you found the bug in, and which operating system and version number you're using?

The Bug Is Reproducible[edit]

If you can reproduce the bug, leave a comment which:

  • Says that you can reproduce the bug.
  • Re-states what you expected to happen, and what actually happened.
  • Goes over the steps you took to reproduce the problem. This should be as detailed as possible, including the commands you ran, input you supplied, and any output you got back.
    • If you're up for it (and if it's relevant) attach a short, standalone program that reproduces the bug and add it to the ticket. This will be a helpful basis for writing test cases.
  • List all versions of project in which the bug was and wasn't present for you.
  • List all operating systems on which the bug was and wasn't present for you.

For example, you might write:

Thanks for your bug report! I was able to reproduce the issue on versions 3.1 and 3.2 of the project on OSX 10.8.4 following exactly the steps you made in your report. I also tried to reproduce on an older machine of mine which runs OSX 10.7.0, using version 3.1 of the project, and I couldn't reproduce the error there, so perhaps it has something to do with the operating system?

The Bug Is Not Reproducible[edit]

If you can't reproduce the bug, leave a comment which:

  • Says that you can't reproduce the bug.
  • Goes over the steps you took to reproduce the problem. This should be as detailed as possible, including the commands you ran, input you supplied, and any output you got back.
  • List all versions of project in which the bug wasn't present for you.
  • List all operating systems on which the bug wasn't present for you.

Reviewing Patches/Pull Requests[edit]

If you want to work on reviewing patches, filter the issues you see so that you're only looking for "open", "needs review", or "has patch" issues. Again, some projects use different terminology, so you may want to ask a mentor to help you figure out what to filter for. You're looking for issues where a problem has been reported and a pull request or patch has been submitted.

Some issue tracker systems have a standard way to display patches that fix an issue. For instance, Github will show pull requests that reference an issue in the thread for that issue. Bugzilla will show patches in a list of attachments. Other systems require contributors to make commits and then manually leave a comment linking to the commit. It may take a bit of practice to get good at figuring out when when a patch has been submitted.

Once you've found a patch, you can review it by applying it to the project and seeing if it addresses the issue reported, either by fixing an issue or adding an enhancement. Here is a checklist you can use when making your review:

  • Does the patch apply cleanly, or does it cause new errors and/or test failures?
  • Does the patch address the problem reported?
  • Does the patch implement the solution in a straightforward way, or is it confusing? (It's okay if you're not sure whether the solution is straightforward or not! You can always ask why the submitter designed the patch the way they did.)
  • Is the patch accompanied by new tests that address the bug or the new functionality?
  • If the patch includes tests, make sure that the tests fail when the change is reverted (otherwise it is not a good test).
  • If functionality was added or changed, is the patch accompanied by new or updated documentation?

Here is an example comment you might leave:

jesstess, thanks for your patch and tests! The docstring for parse_request needs to be updated as part of this change.

Other than that, the patch looks correct from my inspection, and applies cleanly. I verified that with the patch applied, the reproducer no longer raises a ValueError and instead prints 42 as expected. make patchcheck also reports no errors, and the test_httplib tests still pass. I confirmed that the tests for parsing unicode strings that were added in this patch exercise the bug, as they fail with the code changes reverted and pass with the full patch applied.

The implementation looks straight-forward to me, although I'm not sure why you chose to separate your changes out into a new function. Can you explain your reasoning?