guidelines issue tracking - adeck/ansible-deployments GitHub Wiki
Issue Tracking Guidelines Index
How to Use This Document
This is a living document; anytime the list of labels or milestones is modified, or the way they're used changes, this must be changed to reflect that. The issue tracker, along with the wiki and the code itself, is one of the most important components. Without a consistent and standards-based use of the issue tracker, things will rapidly go downhill.
Labels
General-Purpose Labels
While how to use most of these should hopefully be obvious, for clarity's sake their use is documented here.
| Label | Description |
|---|---|
| clean-code | Any ticket which relates to refactoring code, changing the existing coding guidelines, or which otherwise relates to making the codebase more readable / maintainable. |
| documentation | For all tickets relating to documentation or the wiki. |
| issue-tracking | For all tickets related to issue tracking, the specific issue-tracking system in use, the way it's used, the issue tracking wiki page that you're currently reading, or any of the topics covered herein. |
| security | Anything that relates to the security of the code written here / the systems that code is run on. So, defense-in-depth measures, exploitable vulnerabilities, permissions and access control, privacy, anonymity, encryption, and the like. Worth noting that not every issue which relates to a security-related role should have this label; only those issues which actually relate to the security functionality of a security role should be given this label. So, a task to simply rename variables in the firewall role, for example, probably shouldn't have the security label. |
| testing | Anything that relates to testing the code should be given this label. Specifically, this should only be used to refer to tests of code; in other words, if documentation or the issue tracker are to be tested, or if changes are to be made to the aforementioned on a trial basis, that would not fall under this label. If those additional activities start happening often enough that a label would be useful, they will get their own labels. |
Statuses
The following labels relate to the status of a given ticket; whether action is being taken on the ticket, whether action is planned for the ticket, and the nature of that action.
| Label | Description |
|---|---|
| in-progress | There should only be one ticket labeled in-progress for each person. As the label suggests, it means the ticket is being worked on by the person to whom it's assigned. More specifically, it means the person to whom it's been assigned will not be able to work on other tickets until they've done with this one; so, it shouldn't be temporarily removed just because someone's using the bathroom or sleeping. Should only be removed when a ticket is closed, or if the asignee has switched to another ticket (for whatever reason). |
| on-deck | Indicates that this ticket is on the radar of the assignee, and that once the assignee has completed their current in-progress task, this is one of the tasks they've decided to take on. Essentially, the assignee has called "dibs". That having been said, if they don't close it, they have to deal with that shame. |
| blocked | The ticket cannot be dealt with until one or more other tickets are dealt with; those other tickets should be linked in the ticket labeled as blocked. You can link other tickets by simply putting an octothorpe followed by the ticket number (e.g. #23 will automatically become a link to ticket number 23). |
| wontfix | This should go on any closed ticket which has not been resolved, but for which there is no plan for resolution; issues being put off indefinitely. This is to be used primarily for feature requests, and for it to be applied to any other type of ticket requires a five day grace period during which the issue is labeled may-not-fix before being closed and given this label. |
| may-not-fix | If an issue is not a feature request, it may not be closed or assigned the wontfix label until it has had the may-not-fix label for five days. The person assigning this label must comment as to the reason when they assign the label. During the five subsequent days, if no one disagrees with the designation or removes the tag, the issue should be labeled wontfix and closed. |
| ..................... |
Priorities
The priority associated with a given issue is indicated by one of the following mint-green labels. While the exact priority of a given issue can be difficult or impossible to determine, it is useful to be able to group tasks by generally how important they are and, correspondingly, how much effort should be expended on them. Hopefully the below table will clear up any questions.
| Label | When to Use | What It Means |
|---|---|---|
| P1 | When something needs to be fixed yesterday. Anything labeled security and bug with a CVSS score higher than 4.0 (this helpful calculator should make calculating that easier) definitely qualifies. |
Should be fixed as soon as possible; as soon as someone qualified isn't working on another P1, they need to be fixing this until it's fixed. There should be very few of these. |
| P2 | When something is important, but not dangerous. Anything labeled both security and bug which isn't a P1 must be a P2. |
Should be started as soon as possible, and completed within a week of being started, if possible. There shouldn't be many of these. |
| P3 | When in doubt, make it a P3. Regular tasks and everyday maintenance falls under P3. Anytime someone's working on some new piece of functionality, that's a P3. | These are the body of most people's work. Anyone not working on, or not qualified to work on, a P1 or a P2 can work on these. No individual should be working on more than two of these at any one time. At least eight hours a week should be spent on each of these. |
| P4 | This is for feature requests, and other items which would be nice to have, but which are not a primary part of the plan. | Each person needs to be working on at least one of these at any given time, and when in progress must spend at least a few hours each week on it. Why? Because if only complete disasters get fixed, and only primary functionality is present, details get missed and small things don't get fixed. |
Project Labels
For every new project, that project should be assigned an orange label (to match the other project labels) and added to the list of roles. The project label must bear the same name as the directory under projects associated with the given project. Items should only be given a label associated with a particular project if the ticket is specific to that project and only that project. So, for example, despite the fact that the ferm role should be included in all projects, a ticket which affects the ferm role shouldn't be labeled with all the project labels unless the issue only relates to how the ferm role is behaving with respect to that project.
Tasks, Jobs, and Enhancements
These categories are mutually exclusive. Whether something should be tagged as an enhancement, a job, a task, or none of the above depends on a few factors, and (most importantly) has practical implications.
Only an actual collaborator on the repo should be able to mark something as a task or job. This is the case because knowing whether something is doable, how long it should take, and who it should be assigned to, can only be done by someone who has a solid understanding of the codebase.
Additionally, the labeling should not change unless substantially new information comes to light. For example, something shouldn't go from a job to a task simply because you've put 16 hours into it and have fewer than four hours left of work; that still counts as at least a job, and will continue to be one even when closed.
Tasks
It's a task if any of the following are true...
- It is expected to take four or fewer hours to complete.
- The exact steps necessary to complete it are already known. In other words, the person to whom the task is assigned does not anticipate needing to refer to any documentation to complete the given task.
Jobs
It's a job if any of the following are true...
- It is expected to take two or fewer days to complete.
- The person to whom it's assigned is knows what generally what steps they would need to take, and knows exactly what documentation they would refer to to fill in the gaps.
Enhancements
It's an enhancement if any of the following are true...
- It may take longer than a two days to complete.
- It would involve some change to the codebase or development process, or the change it suggests would involve some other kind of significant change.
- It is a feature request.
- It would be a task or a job, but the person labeling it is not the person to whom it's assigned.
New Labels
Ideally, we do this as little as possible, and only if there are at least four issues to which the new label would apply, and at least four issues to which the label wouldn't apply. Since the point of labels is to break the caseload of outstanding issues into smaller groups, a label that would be applicable to all issues would be just as useless as a label that would be applicable to only one or two issues; creating labels for either would rapidly lead to having so many that the issue of having too many labels would arise. Which would be silly.
If you feel a new label would be useful, open an issue tagged with issue-tracking, enhancement, and P3 and wait for feedback. Do not simply create the label.
Milestones
Regular Milestones & Ticket Auditing
To create a milestone, there must be three issues which would fall under that milestone, and which are not currently assigned to another milestone. The milestone must have a description of at least one grammatically correct sentence with a different phrasing from that used in the title, and it must have a "due date" assigned (even if that date is only tentative).
When the due date is reached, if the milestone hasn't been closed, a P3 issue must be opened, assigned the P2 label, and added to the no-backlog milestone. This should prompt a discussion between the people working on the milestone, and re-evaluation of all the outstanding issues associated with the milestones. Primarily, this issue should focus on the issues' associated time status (task, job, or enhancement), priority status (P1 through P4), goal status (may-not-fix and wontfix), and asignees.
This no-backlog issue should be closed once all the outstanding milestone issues have been reviewed / re-evaluated and a new due date for the milestone has been set.
New tickets should be assigned to the no-milestone milestone, which should have a recurring monthly due date.
Ongoing Milestones
For an ongoing milestone (one which lacks a due date), it must be approved. A ticket should be opened with the issue-tracking, enhancement, and P3 labels. This ticket should specify:
- the proposed milestone name
- the proposed use case / description for the milestone, and more specifically when tickets would be assigned to it
- at least two situations in the past where it would have been helpful to have
- why it makes more sense as a milestone than a label
This is done to prevent a proliferation of milestones without expiry. It's also important, before you suggest a milestone without expiry, to ensure that very few tickets would actually be eligible. We want as few tickets to fly under the radar as possible, and being associated with a milestone that never undergoes a ticket audit (as described above) is one way for tickets to be ignored.