Software devours the world, open source devours software! The issue driven development model based on an issue tracking system has not only had a significant impact on the development process of open source systems, but more and more companies and organizations in the commercial software development space are also using the issue-driven development approach.
For the issue mentioned here, we can’t just understand it as bug in the past, that would be too narrow and outdated. Today’s issue carries “all-inclusive” information, and anything related to the project/repo is proposed in the form of an issue, including new features, bugs, improvements, technical proposals, tasks, discussions, and so on.
With the issue tracking system, we will face a problem, that is, how to organize issues to make the issue-driven software development process more scientific and efficient? For this reason, I have read several empirical study papers on issue organization and management.
Here is a synthesis of the paper’s findings.
- The use of labels (label) facilitates the resolution of issues in software projects.
- Projects that use the multiple label (label) feature can manage their issues more effectively.
Did you get the keyword? That’s right, “multi-tag”. Using multiple tags to organize the issues can be more effective in managing the issues. So which tags to set and how to tag an issue with multiple tags? On these questions, paper does not give the answer, or we need to practice to explore.
In this paper, I will give a multi-label based issue-driven software development practice for your reference, but NOTE: this is not a best practice, but only a feasible (even immature) practice, you can also expand on the basis of the practice.
1. label management, classification first
Most issue tracking systems have a set of built-in labels that you can choose to use directly, for example, the following are the default issue labels provided by github and gitlab.
-
github’s default set of issue labels
- bug
- enhancement
- document
- duplicate
- good first issue
- help wanted
- invalid
- question
- wontfix
-
gitlab’s default set of issue labels
- bug
- enhancement
- documentation
- suggestion
- discussion
- support
- confirmed
- critical
At the same time, the issue tracking system also supports custom labels, but we can’t just define new labels mindlessly, we have to consider the utility of labels and categorize them scientifically (categorizezation).
Let’s analyze the default labels provided by github and gitlab above, most of them are used to represent the category of an issue (category), so we first need to define a set of labels that can represent the category of an issue, which can be customized by combining the default set of labels above and the needs of the daily work context.
For example, here I have customized the set of labels that represent the category of an issue as follows.
- bug
- feature
- task
- proposal
- enhancement
- suggestion
- discussion
These labels are the basis for the entire issue-driven development. Each newly created issue must first be given (assign) a label that represents the category, and in line with the principle that the most commonly used labels should be as short as possible, we use a single word for each label, without using a prefix string.
Next, we define several sets of labels.
-
A collection of labels representing workflow
-
workflow/confirmed
-
workflow/accepted
-
workflow/need-investigation
-
workflow/wait-for-info
-
workflow/need-proposal
-
workflow/need-review
-
workflow/declined
-
workflow/blocked
-
workflow/wontfix
-
workflow/duplicate
The reason for the workflow prefix is to reduce the burden on the developer in choosing a label when considering what kind of collection the label actually is, by prefixing it at a glance.
-
-
A collection of labels representing priority
- priority/critical
- priority/release-blocker
- priority/security
- priority/urgent
-
A collection of labels representing components involved
- component/proto
- component/tracing
- component/logging
- component/metrics
- component/api
- … …
When defining a collection of labels for different functions, it is important to note the following points.
-
Generally there is no need to customize a label like todo
Which is put into the issue system of the new issue is not to todo, and then define a todo label some superfluous feeling. In addition, many code repository management tools with Kanban function will automatically include your newly created issue in the todo column of the milestone Kanban board after the issue is included in a milestone.
-
The issue version information can be calibrated with milestone
We generally do not need to create a label that holds version information, but can use milestone (milestone) to identify the version attribute of the issue.
-
Define the label collection from the top down
For the same organization, consistency in workflow is important, so that we need to define top-down collections of labels, rather than each project defining its own collection of labels.
If you are using gitlab (according to a survey, most companies in China use gitlab), since groups in gitlab support label definitions, we can define a set of label collections in the top-level group, so that the subgroups and project repo can “inherit” this set of labels.
If the project has personalized label requirements, the project can customize its own labels on top of the unified set of labels, which will avoid a lot of duplicate definitions and maintain the consistency of the label set, laying the foundation for subsequent workflow operations.
After defining these types of issues, let’s look at the process of creating an issue and driving development “up”.
2. multi-label issue-driven workflow
Planning and creating milestone
Regardless of which development process is used (waterfall, iterative or agile), the end result is to output deliverables, and we usually output each version deliverable as a milestone, so before creating an issue, we first plan and create the milestone, and milestone itself also contains the issue’s version attributes.
If you’re using gitlab, you can set milestones either at the group level or on a specific project.
If you’re outputting a product that contains multiple services, setting milestone at the group/subgroup level will unify the release version of the product.
In addition, we can create backlogs at the appropriate level as a long-term milestone to collect issues that have not yet been assigned a version.
Once the milestone is planned and created in this way, the leader can then milestone oriented management. Next, we can create issues.
Create an issue, select a category label
Our workflow requires that whenever a developer, tester, leader or related person creates an issue, make sure to select a category label.
- bug: a problem that causes a product or service to not work as expected
- feature: a new feature or non-feature
- enhancement: Enhancement and optimization of existing feature mechanisms
- task: a product/service related task that may not require coding
- discussion: initiating a discussion on a specific topic, requiring active participation of team members
- suggestion：A suggestion for the product/service, need team members to participate in review
- proposal: a technical proposal for a functional or non-functional feature of the product, the proposal content of the proposal is filled in the issue by markdown syntax for everyone to review
Choosing a category label for an issue is the prerequisite and foundation for driving the workflow to flow subsequently.
Select a release milestone
Select a milestone for the issue you just created.
For bug, feature, enhancement type issues, select the version (milestone) in which to finish. For issues that have not yet been defined, you can put them in the backlog milestone and put them back in the version milestone later.
For other category type issues, such as proposal, discussion, you can first do not need to choose the version milestone, can be put into the backlog first.
Selecting a label for the workflow category
Next, we need to give the appropriate workflow label to the issue according to its category to get the issue into the workflow.
-
For bug type issues
For bug-like issues, workflow/need-investigation or workflow/wait-for-info can be selected if it is not clear whether it is a bug or there is insufficient evidence.
After investigation, if it is determined to be a bug, then a developer or leader needs to remove the workflow tag above and then reassign the workflow/confirmed tag. Only issues that are confirmed can be included in the version milestone to track up, and bug issues that are not confirmed can be put into the backlog milestone pending confirmation.
If it is a duplicate issue, workflow/duplicate can be selected, and then we can close this duplicate issue.
For non-bugs, or issues that do not need to be fixed after evaluation, you can select workflow/wontfix and then close issue.
-
For feature or enhancement class issues
workflow/need-investigation if technical research is required.
If a technical proposal/design implementation solution is needed, workflow/need-proposal can be selected.
workflow/wait-for-info if more information is needed from issue proponents.
If accepting feature or enhancement type issues, you can select workflow/accepted and then confirm that it is in the correct version milestone.
-
For proposal-type issues
For proposal-type issues, the team needs to decide whether to accept the proposal, initially you can choose workflow/need-review, after review you can choose whether to accept, if accepted, choose workflow/accepted, once accepted, you can newly choose which one to include milestone. If not accepted, then select workflow/declined (rejected), and then close issue.
Finally, for issues that cannot continue temporarily for various reasons, you can select workflow/blocked and then select the workflow label for the issue again after the blocking problem is lifted.
Select issue priority (optional)
Issue usually does not need to choose a priority. As long as it is included in the release milestone, it needs to be completed within the milestone.
However, we have customized some priority labels for “focused” attention, for flexible use.
- critical - critical issues, which must be completed within the milestone
- release-blocker - usually for bug issues, if the issue is not resolved, the milestone cannot be completed and released on time
- security - security issues, to raise the priority of the issue
- urgent - urgent burst issues, can be used for patch issues
Select component (optional)
Selecting component class tags for issues is more for statistical and filtering purposes. Here logging, tracing, metrics, etc. are for example only, you can define the necessary component tags according to your product/project context.
workflow label based driver
Once we have completed a round of label assignments, the developer starts subsequent work based on the status of the issue in workflow, and once the work is finished, the workflow label of the issue is changed until the issue is closed.
3. Summary
This paper presents a practical idea of multi-label issue-driven software development, through which a team can run organically around the issue tracing system.
If there are many issues and it is inconvenient to manage them manually, issue bot can be introduced to automatically maintain the status of the issues and remind them according to the set rules, which I will continue to talk about if I have time.