Bug Tracker Issue Management ============================ Here are the present Issue Manager's (thorkilnaur's) ideas about how to manage the issues on the darcs bug tracker `http://bugs.darcs.net/ `_. The basic desire is to ensure that all issues move toward some sort of stable state, reflecting that issues that are raised get suitable attention and are resolved. By clarifying the use and interpretation of the data in the bug tracker, it is hoped that it becomes easier to use and also a more valuable source of information. Initially, the use and interpretation of the issue status, priority, and topic/keyword values are described. Then various tasks that serve to push issues forward are described, supported by simple bug tracker queries. While anyone is, of course, free to perform any of these tasks, it is ultimately the responsibility of the issue manager to ensure that no issue is forgotten. The set of tasks described certainly does not exhaust the possible ways that one may wish to make use of the bug tracker, so a final section describes other possible uses. In particular, the questions raised in `BugTracker `_ are given some sort of response. Bug Tracker Status Values ------------------------- The status value of an issue in the bug tracker summarizes the status of the issue. The actual status values that can be used at any time can be extracted from the bug tracker itself: `http://bugs.darcs.net/status `_. The use and interpretation of status values are described in the following table. \|\| *Status* \|\| *Description* \|\| \|\| ``unread``\|\|<(\|2> A new issue enters the bug tracker in the ``unread``status and discussion of the issue generally happens in the ``chatting``status. It is a clear goal of the issue management process that issues do not remain in either of these states for a long time, but rather enter one of the other states, depending on the outcome of the discussions. \|\| \|\| ``chatting``\|\| \|\| ``need-info``\|\| This bug can't be addressed until more information is provided by the submitter. The bug will be closed if the submitter doesn't provide more information in a reasonable (few months) timeframe. This is for bugs like \`It doesn't work'. What doesn't work? \|\| \|\| ``need-volunteer``\|\| The issue needs to be addressed by a volunteer (not excluding the submitter): The issue may be a wishlist or new feature issue that needs to be discussed, to decide whether to actually carry out the desired change. Or some definite work needs to be done, such as investigating a performance issue in detail or even, assuming that outstanding questions have been answered, carrying out the work indicated. The nature of the work must be described in the messages of the issue. In some cases, it may make sense to assign the issue to some specific person, but in status ``need-volunteer``, this should be interpreted as a useful hint, not as an obligation. \|\| \|\| ``in-progress``\|\| Work is in progress to solve the problem described by the issue. This state should be set by the person who decides to work on resolving the issue. At the same time, the issue should be assigned to that person. \|\| \|\| ``deferred``\|\| This status is used for issues that are minor bugs that are deemed safe to leave unresolved. It is used mainly to reduce the number of unresolved issues in other states. The reason for putting an issue in the ``deferred``state must be described in the messages of the issue. \|\| \|\| ``duplicate``\|\| The issue is a duplicate of another issue. That other issue is mentioned in the messages of the issue and also, perhaps, as a superseder. \|\| \|\| ``wont-fix``\|\| This bug won't be fixed. Possibly because this is a choice between two arbitrary ways of doing things, possibly because nobody has the time to implement and maintain a feature, possibly because changing the behaviour will cause other, worse, problems for others, or possibly for other reasons. \|\| \|\| ``presumed-dead``\|\| An issue which cannot be reproduced or with questions left unanswered for a long time. \|\| \|\| ``resolved``\|\| The issue has been resolved. The state of the issue and reason for considering the issue resolved must be described in messages of the issue. \|\| As at Dec 2008, the following legacy status values exist. DO NOT use them. - :: testing - :: resolved-in-unstable - :: resolved-in-stable Bug Tracker Priorities ---------------------- The priority value of an issue summarizes the importance of the issue, as seen by the darcs team. The importance of the issue, as seen by the reporter of the issue, must be apparent from the messages of the issue. The actual priority values that can be used at any time can be extracted from the bug tracker itself: `http://bugs.darcs.net/priority `_. The priority values are described in the following table, mostly taken from `http://roundup.sourceforge.net/doc-1.0/user\_guide.html `_. \|\| *Priority* \|\| *Description* \|\| \|\| ``critical``\|\| Makes Darcs unusable or mostly so, or causes data loss, or introduces a security hole. \|\| \|\| ``urgent``\|\| A bug which has a major effect on the usability of a package, without rendering it completely unusable to everyone. \|\| \|\| ``bug``\|\| The default value, applicable to most bugs. \|\| \|\| ``wishlist``\|\| For any feature request, and also for any bugs that are very difficult to fix due to major design considerations. \|\| \|\| ``feature``\|\| Want missing functionality \|\| \|\| ``not-our-bug``\|\| The issue cannot be resolved within darcs itself \|\| \|\| ``silly wishlist``\|\| Legacy; DO NOT use. \|\| This description is not in actual accordance with the way these priority values are presently used. For example, many issues that describe avoidable bugs are actually given the ``bug``priority. However, such minor inaccuracies seem harmless and the present issue manager is not going to launch an attempt to change the way these priorities are presently used. The most important distinction seems to be between issues that require high attention ({{{critical}}}/{{{urgent}}}), bugs that can be worked around ({{{bug}}}) and the rest. The priority will typically be set by the issue manager or another member of the darcs team during the initial discussion of the issue. Bug Tracker Keyword/Topic Values -------------------------------- Each issue can be given a list of keywords/topics and this is really an open-ended possibility of describing any desired property of selected issues. The actual keyword/topic values that can be used at any time can be extracted from the bug tracker itself: `http://bugs.darcs.net/keyword `_. The use of keywords/topics is not covered by any particular rules, so new keywords/topics can be defined and used as one sees practical. However, it is important that all the keywords/topics are suitably described on `BugTrackerKeywordTopicValues `_ to make their intended use clear. Bug Tracker Issue Management Tasks ---------------------------------- Initial response and discussion ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To ensure that recently entered issues and issues being discussed are suitably handled, these bug tracker queries are useful: - `Unread issues, grouped by priority, oldest first `_ - `Chatting issues, grouped by priority, oldest first `_ - `Unread or chatting issues, grouped by priority, oldest first `_ A main concern when discussing an issue is assigning a suitable priority to the issue and also appropriate keywords/topics. Issues should not be left inactive in any of these lists for a long time. Anyone are welcome to help with that, but the issue manager is ultimately responsible. Follow up on requests for further information and work ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To check progress on questions and requests to get some actual work done, this bug tracker query may be used: - `Need-info or need-volunteer issues, grouped by priority, oldest first `_ Depending on the priority, issues should be allowed to remain outstanding in this list for a while. It should be clear from the messages on any issue who is expected to react. If further information is supplied, the issue may sensibly be put back into the ``chatting``state for further discussion. Or a volunteer may take a ``need-volunteer``issue to the ``in-progress``state and start working on it. If an issue has reamined in this list for a while, one possible reaction is to remind people about the issue, by adding a message to the issue or using the mailing list. If a question (perhaps to the reporter on an issue) remains unanswered for a long time or an issue cannot be reproduced reliably, it may be a candidate for the ``presumed-dead``status. Checking in-progress issues ~~~~~~~~~~~~~~~~~~~~~~~~~~~ The in-progress issues are: - `In-progress issues, grouped by priority, oldest first `_ In-progress issues are assigned to a person who is responsible for the work and bringing the issue forward. When that person, very possibly in collaboration with reviewers and others, decides that the issue is resolved, that person changes the status to ``resolved``. The exact state of affairs at this point can vary a lot, but the clear intention is that the responsible person should not need to be involved in further handling of the issue, such as ensuring that is gets reflected in a suitable release. This leaves some additional work outstanding, of course, but it seems hard to avoid. If an issue is in progress for a while, it may make sense to follow up on the status of the issue. Other Activities Related to the Bug Tracker ------------------------------------------- Which issues are triaged? ~~~~~~~~~~~~~~~~~~~~~~~~~ This question is raised on `BugTracker `_. The scheme described above intends to define clearly how an issue moves forward in status and that seems to be the main concern. Whether an issue can be said to be triaged seems to be of secondary importance. Clearly, the issues in the group that need initial response and discussion are those that need most urgent attention, so it may make sense to say that all the remaining issues (in particular those with ``need-info``and ``need-volunteer``status) are the triaged ones and consider the issues with ``unread``or ``chatting``status as un-triaged. But one should keep in mind that issues can revert to the ``chatting``status and hence would become un-triaged in this view. When will a solution to a particular bug issue be released? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ With the present scheme, the bug tracker will not reflect this information, except as it may appear from the messages on the issue. This is deliberate, not because it is desirable, but because requiring this information to be available from the bug tracker seems to burden the developers unacceptably. Figuring out where in the process of things a particular issue can be found will remain a bit of a research activitity, involving a number of separate sources. What is the status of `http://bugs.darcs.net/issue778 `_ ? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Another question from `BugTracker `_, assuming `http://bugs.darcs.net/msg4431 `_ to be the latest message: The answer here would be: We need a response to proceed (or some other reproduction of the problem) and if we don't get the answer, we may eventually set status ``presumed-dead``.