A proposal to streamline workflow with organized GitHub labels

[Farhad-Shabani]

Overview

This initiative aims to give a systematic approach to defining and using Github labels. It is developed with a look at maximizing coverage, attaching more purposeful information, and organizing issues and pull requests in a simple and effective way.

Description

The proposal originated from the idea of grouping labels into a few categories so that whenever an issue or pull request is opened, a collaborator can simply ask some simple questions to assign the right labels. He or she should answer Why (the purpose of fulfilling the issue/PR), Which (the part of the product/project it relates to), and How (The way it should be organized to perform).

To make it easier to identify and distinguish labels, they have been split into four categories: Objective-level, External-level, Internal-level, and Administrative-level. Each category has a designated color range and begins with the first letter of the group. This allows individuals to easily search, attach or review labels when necessary.

Before providing more information, it's important to note that each group has been further divided into two sub-categories for the sake of clarity, having more context, to make it easier to define new labels. A tag can be created from any perspective and does not have to come from these sub-categories. Here are more details about each group(You can also navigate to this diagram):

Objective-level labels

Objectives can be broadly categorized into two groups: functional and quality (non-functional). These objectives consist of tags that identify which aspects of the product's quality would be improved or which functionalities or features will be added when addressing an issue. Considering the objective standpoint makes it easier to determine how to prioritize and allocate resources.

Internal-level labels

The internal level provides an inside view and focuses on anything related to the current scope of the product. These tags identify the relevant units/modules or processes within that product.

External-level labels

This level of tags encompasses anything that is connected to external projects, products, or businesses and aims to address user requirements that fall outside the current scope of the product.

Administrative-level labels

This level tracks administrative aspects such as status, priority, complexity, and anything related to time and resource management. This includes:

• Tracking and workflow-related issues
• Priority (urgent vs. non-urgent)
• Importance (trivial vs. critical)
• Complexity (to help allocate development resources based on expertise)
• Status (including blocked, breaking, etc.)

This level also offers a wider range of colors to provide more options for defining tags.

Wrapping up

Given the above descriptions, members can search for the appropriate labels by asking themselves the following questions and looking for the corresponding tag that begins with the first letter of its group:

1. What is the purpose (Why)? It is implicitly known by selecting which quality/functionality would be impacted after resolving it.
2. Is this issue related to the internal or external scope of the product/project? (Which)
3. To which unit or party of that boundary does this issue pertain? (Which)
4. Should it be marked as a specific task, so as to adjust workflow, plan, or resource allocations? (How)

It can be viewed as a flexible repository-wide system that can be used as a basis for defining labels for any internal project. Having the categories can help to organize a large number of labels under a few classifications. Though, this might not completely cover every angle, making it easier for collaborators to find the fit labels, and requiring less maintenance from admins.

Furthermore, if multiple projects adopt the same approach while using their own labels, other teammates will be able to understand issues agreeably and cross-team communication will be more practical, particularly from objective and administrative standpoints.

---

For Admin Use

• Not duplicate issue
• Appropriate labels applied
• Appropriate milestone (priority) applied
• Appropriate contributors tagged
• Contributor assigned/self-assigned

[Farhad-Shabani]

@seanchen1991 I would appreciate your opinion on this. That’s what came to my mind regarding organizing tags and admin-related stuff from our last 1:1 meeting. I put it together hoping to help and If you’d like to consider any parts you see fit. Perhaps I missed some details, so we can consider it as an initial draft and go further if this works.

[seanchen1991]

This is an awesome initiative! To me it seems like the immediate takeaways in order to put this proposal into action is to:

• Change the tags such that they match the proposed color coding
• Add some documentation in our issue and PR templates that lay out the process of how to assign a tag of each category

[plafer]

LGTM for ibc-rs as well! We can start with an initial set of tags that we think are going to be useful, and over time remove the unused ones and add whichever we found were missing.

Great initiative!

[ancazamfir]

thanks @Farhad-Shabani, looks good! I am looking forward to seeing these applied to the issues for one project to get a better feeling.
Some minor comments:

• Some objective tags under non-functional category are arguably functional imho but maybe we don't need to debate that since the categories are not explicit.

• What exactly is enhancement, what does it enhance?

• re:

Importance (trivial vs. critical)

trivial suggests complexity, maybe non-critical (especially that these tags don't have the importance context).

• Can we also add some Risk tags (something like high-risk/ low-risk or risky/ safe), e.g. for projects/ tasks with high risk dependencies, or high complexity, or research frontier unknowns.

[Farhad-Shabani]

thanks @Farhad-Shabani, looks good! I am looking forward to seeing these applied to the issues for one project to get a better feeling.

🙏
I begin by applying it to Hermes. It definitely needs to be improved in practice

• What exactly is enhancement, what does it enhance?

That was among the general tags we already have. But you are right, looks vague.

trivial suggests complexity, maybe non-critical (especially that these tags don't have the importance context).

Correct. I'll revise it.

Can we also add some Risk tags (something like high-risk/ low-risk or risky/ safe), e.g. for projects/ tasks with high risk dependencies, or high complexity, or research frontier unknowns.

Ofc, Will add it

Thanks for these details

[Farhad-Shabani]

*What exactly is enhancement, what does it enhance?

Re-checking where we've used the enhancement label before, we mostly used it for adding new features or refactoring that made things easier to maintain. we may keep it for searching the history, but use it from now on for "adding new features" and create a maintainability label to separate these two purposes

[ancazamfir]

Re-checking where we've used the enhancement label before, we mostly used it for adding new features or refactoring that made things easier to maintain. we may keep it for searching the history, but use it from now on for "adding new features" and create a maintainability label to separate these two purposes

Why not use "feature" then?

[Farhad-Shabani]

Why not use "feature" then?

I was concerned about the issues that have been labelled with enhancement before, but do not fully comply with renamed feature. Although I agree to having it as feature to better manage our ongoing tasks rather than worrying about past ones

[adizere]

Why not use "feature" then?

I was concerned about the issues that have been labelled with enhancement before, but do not fully comply with renamed feature. Although I agree to having it as feature to better manage our ongoing tasks rather than worrying about past ones

+1 We don't need to worry about past use of labels necessarily.