Managing Trilinos Project Issues

Overview

Using GitHub Issues

Processing New GitHub Issues

Overview

The Trilinos Project uses the Kanban agile software development process to improve project productivity and increase visibility and transparency of activities. The primary issue tracking tool used by the Trilinos Project is GitHub Issues.

In addition to GitHub Issues, some Trilinos deliverable tracking takes place in the issue tracking tools of Trilinos customers. This tracking can be any combinations of high-level, (similar to SCRUM epics), or at a lower-level (similar to SCRUM stories or tasks) depending on specific circumstances. The process for using customer tools varies by customer.

The basic premise of Kanban is:

1. Limit WIP:

• By limiting the work in progress (WIP, i.e. the number of distinct project tasks that are active at any given time), productivity is improved because the overhead of swapping between distinct activities is optimized.
• Weaknesses in the development workflow that create bottlenecks in productivity become evident when an in-progress task is taking longer than expected. Rather than permitting the team to move on to another task, the team must identify and fix the productivity bottleneck, leading to a better process in the future.

1. Pull scheduling:

• Developers only pull new work when their is sufficient capacity to do so.
• Avoids a deadline-based approach. Deadlines are dealt with in a different way (e.g. deadlines on milestones with flexible scope).

1. Just-in-time commitment: Planning and commitment is deferred until the "last responsible moment".

2. Visualize the workflow: Provides a nice board for viewing and managing issues. The board is useful for all stakeholders, including developers, interested users, project leadership, and management.

An excellent overview of Kanban (and Scrum) is provided by Henrik Kniberg and Mattias Skarin. Another useful site for information on Kanban is Open Kanban. Also, here is a nice kick-start example for Kanban.

General Guidance for Trilinos Developers Using GitHub Issues

GitHub provides an excellent overview for using GitHub Issues. Developers should be generally familiar with the features discussed in this overview. Below we assume familiarity with these features and focus on recommended and common use of these features within the Trilinos project.

Using Labels: The Trilinos Project strongly encourages the use of labels, and requires that each issue have at least one label applied to it before it is "accepted" into the backlog. Note that users who do not have write access to the repository cannot apply labels to new or existing issues. The justification for this GitHub (not Trilinos Project) policy is that developers would not want users applying the wrong labels to issues (consider for example if there was an "urgent" label, or something of that nature). More information about applying the right labels, and further details are provided below in the next section.

Trilinos Team Names: Many Trilinos package development teams have created a team in the Trilinos organization on GitHub. By doing this, teams can be "mentioned" in the same way that users can be mentioned. The cost of having a team is simply the maintenance of appropriate team membership. Currently, it is not required that each package have a team associated with it in the Trilinos organization. This is at least partially due to the fact that some packages are orphaned and when maintenance or development needs to be performed on those packages. The Trilinos GitHub issue template firmly guides those filing issues to @ mention at least one Trilinos team or developer (the default is the framework team). The @ mentioned team or developer then can decide who to assign the issue to (if anyone) and/or communicate with the customer who created the Issue about the status of the package and the issue at hand.

Dependency Tracking Strategies: GitHub Issues do not support dependency tracking in a strong way. That is to say, you cannot say that one issue depends on another in the same way you can in a tool like Bugzilla (or Trac, or JIRA, etc.). There are two primary ways dependencies can be noted using GitHub issues. First, you can use a reference, as noted in the overview. References can denote a dependency, or simply that another issue is "related" (a designation that is lacking in Bugzilla). If you reference one issue in another, the referenced issue will have a note added to it saying it was referenced, and listing the issue it was referenced by. The nature of this dependency should be noted in the editable first comment (i.e. the description) for the Issue (see example below). The other way a dependency can be noted is to set up a GitHub Issue Milestone and add the issue to that Milestone. For example, if the customer release 1.0 depends on a GitHub issue, then you can set up a Milestone for customer release 1.0 and list that Milestone in the Issue. This way you can also track progress towards milestones. Note that GitHub milestones can also be used for general Agile Epics (i.e. without firm end dates) to organize related Issues. Also, a set of subordinate Issue tasks (if appropriate) can be listed out in the first comment (i.e. the description) for the parent Issue. And example of this and other relationships may be shown in the Issues description field (i.e first comment) like:

Fix the thing that is breaking the other thing

...

**Blocked by:** #111, #112

**Blocking:** #113, #114

**Tasks:**
* #123: Figure out what the thing should be doing
* #124: Develop the fix for the thing
* Test and verify that this fixes the other thing

This allows the breakdown of a larger Story Issue into smaller Task Issues as needed (but most tasks don't need to be their own Issue tickets).

Processing New GitHub Issues

(Note: a summary of this information is available on the New Issue Cheat Sheet)

When issues are submitted without labels, the below steps should be taken to properly review and categorize the new issue. This can be done by a developer who was mentioned in the issue, or by a member of the team that was mentioned in the issue. (If the framework team was mentioned by default, they will mention the appropriate team/developer so that this process can be followed.) Individual packages may have a policy that the package lead should follow this process for any issue that mentions the package team. Developers are also asked to complete these steps when filing a new issue so that it is immediately properly categorized:

0. Close the Issue if it will never be worked: If the package lead or the capability lead for the area (for an orphaned package) reads over an Issue and decides that it is not appropriate, or realistically will never be resolved, then it is appropriate to close the Issue and state the justification for why the Issue should be closed. Other interested parties should be @ referenced in the comment that closes the issue.

1. Add Labels: As previously mentioned, the Trilinos Project has a policy of requiring at least one label per GitHub issue. The idea is that only those who have push access to the repository can apply labels, so if labels have been applied to the issue, someone has at least done a preliminary review of the issue. Once a label is applied, it will no longer show up in the "Unlabeled" view, so it is important to also complete the remaining steps below, as other developers will not know these have not been completed once a label is applied. Applying all applicable labels is also important, because filtering by label will only work to the extent that the right labels have been added. Here are some common types of labels to consider:

   • Package: Tpetra, Framework (includes CMake, TriBITS, configuration), etc.

   • Category: performance, test, build, bug, enhancement

   • Platform: linux, osx, windows, gpu, manycore

   (Also see the "help wanted" in the "Assign the Issue" item below.)

2. Mention Associated Teams and Developers: Adding a GitHub @ mention for package teams and developers will alert the right people when a new issue is filed. It may also be appropriate to add comments to the issue when mentioning teams/developers.

3. Assign the Issue: If there is an obvious assignee for an issue, it is best to assign the issue so that someone feels ownership of the issue. If that person cannot address the issue due to time or other constraints, they can try to identify an alternative assignee. If no developer appears to have current or future capacity to address the issue, the help wanted label should be applied to the issue. This is a clear indication of a staffing issue that is visible to all stakeholders. Issues tied to important deliverables to be completed during the current and next calendar quarter should have an assignee listed (or the help wanted label applied) to help identify staffing issues. Remember that issues that are not high priority, and for which there is no available staff to work on the issue, can be closed. Doing so prevents false expectations on the part of Trilinos customers.

4. Associate the Issue with a Milestone (optional): There are two types of milestones commonly used in the Trilinos Project:

• Specific deliverable milestones: These milestones are created for specific deliverables with deadlines. Milestones of this type are sometimes tracked in a customer issue tracker. It is not always necessary to use a milestone if labels and other tracking mechanisms are sufficient. The names of these milestones should be descriptive (but short), but do not need to follow any formatting guidelines.
• Quarterly milestones: These milestones help organize issues that need to resolved by a specific date that are not tied to specific deliverable milestones. Adding issues to these milestones, and then filtering by label or assignee helps developers to see what items need to be completed within a specific time-frame. Milestones of this type are of the format "FY17Q2" (due by end of FY 2017, quarter 2).