For Moderators‎ > ‎

Issue Editing Guidelines

Introduction

To make the most of the issue tracker it's important that those of us editing issues aim to be consistent with each other. This page establishes guidelines around making edits to an issue.

Editing the summary line

The summary line is what users see when looking at the list of existing issues of the same type. Feel free to edit it for clarity.

Editing the Type label

Type-Defect is for bug reports.

Type-Enhancement is for feature requests. The distinction between defect and enhancement can sometimes be unclear, but in general any system behavior that was not intended by the developer is a defect and any system behavior that the user desires but can not achieve is an enhancement. Don't reclassify defects as enhancements unless it's clear that the reported behavior was "by design". Typically only a developer familiar with the relevant code can determine that.

Type-Question is for all questions, no matter how general or specific.

Type-New-Video is for requests for new videos.

Type-Comment is for all other comments.

Editing/Setting the Component label

Component-Code is for issues related to the released web app.

Component-Videos is for issues related to the content of the videos or playlists.

Component-Qbrary is for issues related to the unreleased Qbrary component.

Changing the Status

The New status is for issues that have not yet been screened. If you have read an issue and ensured that the summary line, Type label, and Component label are set appropriately, you should set the status to something other than New. If you aren't sure what to set it to, Accepted is the safest bet.

Use the Duplicate status (and specify the appropriate issue id) if the issue already exists in the issue tracker.

Use the NeedInfo status if you need the reporter to provide some additional information. Tip: for some issues there might be extra labels that already contain the information you need (e.g. exercise name, problem number, video id, browser's User-Agent and Referer headers).

Use the Done status only for questions once they have been answered. Don't use it for other issue types.

When in doubt, don't use the Invalid status because doing so will prevent the issue from appearing in the list of open issues where other developers might see it. Use the Invalid status only under the following circumstances:

  • Issues that are meaningless (e.g. test issues) or contain spam, non-G-rated language, or ad-hominem attacks. These issues should be deleted. If you don't have permission to delete issues, tell a project owner about the issue.
  • Defect issues that are clear cases of "user error". In some of these cases, an enhancement issue should be created or referenced that would help keep users from making the mistake.

Type-Comment issues that simply express negative opinions should not be marked Invalid, even if the comment doesn't contain any constructive suggestions. Accepting the issue will allow others who agree with the sentiment to vote for it and we can use that when planning improvements. Many users may not like the way something currently works, but won't have any ideas about improving it. We should still let them sound off.

Type-Question issues that appear to be homework problems should not be marked Invalid. There is no way to determine whether the asker has already attempted the problem, whether the asker is allowed to have help, etc. If they are asking the question to cheat, they will only hurt themselves in the long run. The question will probably go unanswered, but if someone does answer it then the answerer might have got a little extra practice and others might stumble across the question and answer and learn something.

The remaining statuses are only normally used by developers.

A developer uses the WontFix status only when the issue can't be resolved without breaking something else. In other words it is only for issues where the developers have decided to never address the issue. This typically occurs in situations where the developer needed to pick the least bad among various alternatives. It is very rarely used.

A developer uses the Started status (and sets the owner to himself) when he starts work on a defect or enhancement. Try not to be the owner for more than one Started defect and one Started enhancement at a time (i.e. don't bite off more than you can chew). If you think your changes might be controversial or you just want feedback, post your plans as a comment on the issue (or as a wiki page you mention in a comment).

A developers uses the Fixed status when a defect is fixed or an enhancement is implemented. For code changes, developers should include a comment identifying the revision where the associated code changes were committed. At the moment, we don't wait for code changes to be live before setting the status to Fixed. Tip: you can change the status to Fixed and include the revision number automatically by including "Fixes issue xxx" in your commit message.

Comments