Tools

Last modified
Saturday, August 21, 2021 - 14:37

During development a myriad of tools is used to track the development process. Each tool has its own purpose, with its own do-s and don't-s.

Issue tracker

The issue tracker is used to track bugs and other immediately actionable items. Items that are not immediately actionable based on their description (e.g. because they are either insufficiently specific) need to be moved to Discussion items, either in the Ideas or in the Design category.

Use of labels

Labels are used to categorize open issues. Several labels need some more explanation

  • waiting-for-user
    Issues reported by user, which need further clarification of that user, need to be marked with the "waiting-for-user" label after asking the user for further clarification: if such clarification isn't added within 90 days, the issue will be automatically closed. Although this seems harsh, apparently the issue wasn't actionable without the clarification, therefore the issue is best closed without it.
  • wontfix
    This label is assigned to some issues that are being closed without being addressed: the project acknowledges the bug, but decided not to address it. This could either because the corner case is estimated to be extremely rare, a good workaround is available, or the cure is expected to be worse than the decease.
  • regression
    This label is assigned to issues which contain a bug reporting breakage of functionality that was working in the prior minor release series or prior patch releases.
  • blocking
    This label is assigned when an issue that is assigned to a milestone must be resolved before the milestone can be closed.
  • bug:accounting
    This label is assigned when the issue causes incorrect accounting results. This type of issue has the absolute highest priority of needing to be fixed.
  • dataloss
    This label is assigned when the issue causes data loss. Similar to the "bug:accounting", this issue has the absolute highest priority of needing to be fixed.
  • bite-sized
    This label is assigned to issues which are expected to be a good first issue to be picked up by new developers, or which can be quickly solved by a more experienced developer.

Assignment to developers

In general, issues are expected to remain unassigned: experience has it that assigned issues remain unaddressed for extended periods, with other developers hesitant to step in because the issue seems to be "owned" by another developer. A developer may self-assign an issue to manage their work-queue, if the issue is expected to be resolved within 90 days. If an issue has not been addressed or unassigned within 90 days, other developers should assume the issue to be unassigned and available to work on.

Use of milestones

Generally, the project maintains a milestone for each maintenance branch, and the two upcoming releases, except when the next-upcoming release has branched, in which case it's the two after that. E.g., when 1.9 is the next upcoming release and 1.7 and 1.8 are maintenance branches, there are milestones 1.7, 1.8, 1.9 and 1.10; however, if 1.9 has branched, there's also a 1.11. In addition to a branch milestone, there's also a release milestone after the next-upcoming release has branched. In the example this means there's a 1.9.0 release milestone.

Each branch milestone contains the list of bugs that can reasonably be expected to be solved on that branch. In case of maintenance branches, the scope of what can be fixed is generally very limited, due to conservative backport policies.

The 1.9.0 milestone in the example above contains the list of regressions and other bugs that must be fixed before the first release on the 1.9 branch. These are considered blocking, irrespective of whether they have the "blocking" label.

Projects

Projects are used to group issues by topic. They are used to focus attention on a specific topic, providing an overview of the status of development on that topic. In order to be able to provide focus, issues do not have to be assigned to a project; similarly, the project prefers to have only a limited number of projects at any time. After projects get completed (and thus closed), new projects can be opened to shift focus to new topics.

Ideas & Design discussions

In order to keep logged issues actionable, separate tracking is required for items that are not actionable; from there, "the way forward" can be discussed, resulting in actionable items that can be logged as issues.

There are two categories of items that aren't actionable enough: (a) those that need to be made more specific before support from the application can even be contemplated and (b) those where the desired support from the application is clear, but the implementation strategy is unclear.

Items that fall under (a) in the prior paragraph are called "Ideas". Items from category (b) are called "Design".

Wiki

The wiki is used to document past and present state of affairs, mostly with respect to design and implementation of functionalities. Next to that has the wiki proven a good place to store various checklists that are being used as templates for issue-creation to track progress on specific events (new minor releases, EOL-ing a maintenance branch, etc).

The wiki used to be a place to discuss designs before GitHub Discussions was a thing. Some remnants of that era still show in the wiki.