Home Processes Triaging an issue - Labels, Weights

Triaging an issue - Labels, Weights

Last updated on Oct 24, 2024

Issue triage is essential. Keeping a low number of un-triaged issues is a collective responsibility. Any Chatwoot team member can triage an issue. The GitHub labels, projects, and milestones are used to indicate the current state of the issue and whether it is triaged or not.

Using labels

The following are the labels we use right now.

  1. need-more-info: The issue does not have enough information to start working on it. This state requires input from a person outside the Chatwoot organization. If there is no further response from the person after 7 days, close the issue with the reply - "The issue does not contain enough information for us to debug. Please re-open the issue with relevant details."

  2. investigation - An issue can be created with the label bug. If it is not an obvious one, tag it with the investigation and label it correctly after finding the results.

  3. bug - Some of the features are not working. Before adding this label, please ensure that the functionality is not working as per the spec defined while building the feature. If an issue is created with the label bug without the product screenshots/ruby server logs/Linux machine logs etc., please move it need-more-info and ask for further details. Please ensure that you have added a severity label for each bug as described in the following section.

  4. feature-request - This label is used to track new features, which is a significant change to the existing product.

  5. chore - This label is used to track the tech debt and regular dependency updates. If the end customer does not have a say in the changes, these issues should be tagged as chores.

  6. Good First Issue - This label is used when the issue is easy to pick up. Start with these issues if you are a new contributor.

  7. open-for-prs - These are the issues that are not in the immediate milestone and are open to community members if they are willing to.

  8. accessibility - As we are building a global product catering to a broad set of users, it is crucial to make sure that the software is accessible to everyone. This label can be used to track accessibility-specific issues.

  9. documentation - The documentation issues should be in the docs repository. If there is a significant reason to have it on the main repository, mark it with the label documentation

  10. customer-reported-issues - All the issues reported by cloud and paid self-hosted customers should have this label.

Severity

Each bug can be divided into 4 different categories.

  1. severity: 1 - These are critical issues. Apply this label if a feature is broken and there is no workaround for this.

  2. severity: 2 - Apply this label if a feature is broken, but there is an unacceptably complex workaround for the same.

  3. severity: 3 - Apply this label if a feature is broken, but there is a workaround.

  4. severity: 4 - Apply this label if it is a UI glitch or an inconvenience.

Process labels

Every issue goes through multiple stages from idea to development, and each stage is identified using the labels defined for the process.

  1. need-spec - This issue needs a detailed product spec from the product owner.

  2. need-design - The spec for this issue is complete. Need Balsamiq mockup / Figma design to get started.

  3. PR: unreviewed - A pull request is raised, but it is not reviewed by anyone.

  4. PR: reviewed-changes-requested - There are requested changes in the pull request. The person who has raised the PR should address those comments.

  5. PR: partially-approved - Some of the reviewers have approved the PR. In most cases, the QA process can be started once a PR have this label.

  6. PR: reviewed-approved - All of the reviewers have approved the PR, and the PR is good to be reviewed.

  7. in-QA - The review of the work done is completed. It should be QA'ed by another team member.

Specialization labels

  1. frontend - If the issue requires a frontend implementation, apply this label

  2. backend - If the issue has changed in the backend, apply this label.

  3. self-hosted - Everything related to infra/deployment can be labeled as infrastructure

Use weight to estimate the effort required

Whenever a bug or a feature request is presented before, it is always good to estimate the effort required to solve it. Therefore, we use Fibonacci-based weights with additional weight (0.5) for very smaller tasks. You can see the description of the weights below.

  • 0.5 (Tiny): Tasks that don't require a detailed review, can be merged directly. e.g.: CSS issues, copy changes, etc.

  • 1 (Small, but trivial): The exact solution is known beforehand. You just need to implement it.

  • 2 (Small Problem/Bug): Well-defined problem/bug and a solution is known. It requires some investigation to implement the solution.

  • 3 (Medium): Features that are well understood. It needs an engineering investigation to find the correct solution. Bugs that may not have a solution yet

  • 5 (Large): Broad features that require multiple team members to contribute and bugs that are hard to reproduce. Ideally, this should be split into Small/Medium Tasks

  • 8 (Extra Large): - Extremely large features. Must be turned into an epic with several iterative steps becoming issues

Use GitHub discussion for questions

If there is a question about the project, it should ideally be a discussion. If the issue is created with a question, please move it to the Github Discussion and try to answer it from there.