Processes

Triaging an issue - Labels, Weights

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.

Product - Guidelines

This guide outlines different product boards and how we use them internally to track and prioritize the issues, and feature requests. The tool we use: We used [Github Projects] previously. As of now, we use Zenhub to track and manage issues in Chatwoot. Quick Links: - Full Product Board - Customer reported issues - Untriaged issues - Under-investigation issues - Waiting for design input - Ready for pickup Do you like to contribute any changes to this doc? Engage in the discussion here. Properties of a GitHub Issue: - Title & Description: Each issue should have a proper title and detailed instructions explaining the problem (or context about the feature request) - Reported Date: Every issue added to Github would have a reported date, this can be the date when the issue was created or even before that in case of live chat or email support queries. - Due Date: Once the issue is triaged, if it is a bug, it should have a due date added to it. - Estimated Points: Once the issue is triaged, points should be added to the ticket. - Release version (Milestone): Based on the requirements, every ticket should have an associated milestone and should be prioritized in a sprint. General guidelines: - All issues should be triaged and estimated before picking them up. - Each issue should have a clear description and a to-do and it should follow the issue templates. - 8 and 5-pointer tickets should be broken down into 2 or 3-pointer tickets. Triaging an issue: The goal is to triage an issue as soon as possible and to make sure that there is a consistent response from the Chatwoot team to the customers and to the community. image Triaging a bug - Every issue would be considered untriaged unless it has a **ready-for-pickup** or **need-more-info** or **need-discussion** or **investigation** label. - If the issue is reported as a bug, the assignee should try to reproduce the issue and make sure that the case is valid or mark it as need-more-info by requesting the information from the person who created the issue. - If the bug is confirmed then it should have a severity label as defined here. - If the issue requires more time to be investigated, the assignee can mark it as an **investigation** ticket. We should make sure that the issues are not in the investigation queue for a long time. - If the request is a feature request and you cannot immediately respond, add the labels **need-discussion** and **feature-request**. Working on new features: Every feature request needs a product spec. This is done to make sure that we have collected enough information to move ahead and that there is no confusion around the feature when we are trying to build one. - Whenever you need input from the design team, add the label need-design. - Once the design is complete and the product spec is complete, there can a discussion on how this would be split into multiple smaller engineering issues. (These discussions should be done async, create a meeting only if absolutely required) - Once smaller engineering issues are created, this can be prioritized for pickup in the upcoming sprints. Weekly progress retro: - Look at the previous week's issues, and see if we have missed anything. - Follow the template of What went wrong / What can be improved / What went well to discuss the previous week's progress. - Look at the list of customer-reported issues on the call. Prioritize the issues based on the requirements. - Where do we stand on the milestone? (Look at tagged issues for the milestone, and see if we need to move something) Creating and managing issues: Paid Customer Requests: Goals: - Every issue should be triaged within one business day. - Severity 1 & 2 bugs should be fixed within a week. What should be done: When a customer (cloud or paid) reports an issue: - Create the issue in either the Chatwoot main repo or the product repo depending on the information that will be shared. If it has sensitive information, then create it in the product repo. - Tag the issue with customer-reported-issues the label. - Add it to the project Engineering Board. In most cases, this would be done by the people who are talking to the customers directly. What is expected: - Triage the issue. Can you confirm whether the issues exist or not? - Assess the severity of the bug if it exists. Assign the severity label to the ticket. Where to track: You can view all the issues here: Link to the Engineering Board - Customer Reported Issues. Every team member has to check the board every working day so that there are no issues unattended for a longer period of time. Community Requests: Goals: - Every issue should be triaged within four business days. - Severity 1 & 2 bugs should be fixed within the next release. What is expected: - A team member would be assigned to the ticket automatically in a round-robin fashion. - Triage the issue. Can you confirm whether the issues exist or not? - Assess the severity of the bug if it exists. Assign the severity label to the ticket.

Account Suspension & Restoration

This guide outlines the process Chatwoot uses for account suspension or removal. There are various reasons why an account may be suspended, including violations of the terms of service, pending payments, or system abuse. Some suspensions occur automatically, while others are carefully reviewed based on reports from users or community members. 🧸 The process Follow the process outlined below for each suspension: - Carefully review the reported issue. Record the findings in the attached form. - If the account is being used for spam emails, scams, or phishing content, suspend it immediately. - If it's an account that has shown regular usage patterns in the past six months: - If the issue doesn't affect the overall system, email the user to explain the problem. Wait for a response for 24 hours before suspending. - If the issue impacts the stability of the system, suspend the account immediately. Afterward, email the user to explain the reason for the suspension. Once the problem has been fixed, you can restore the account. Ensure you log both the suspension and restoration in the attached form. We frequently encounter these issues, where users might run load tests in a test environment with the Chatwoot widget added to their UI. 🚵‍♀️ Automated suspensions The system would automatically suspend an account in some of the cases below if it qualifies: - No users have logged in to the account for the past 6 months. - The trial accounts with connected third-party channels or using paid features are past the trial period and have not started payments. - There was a payment error (retries failed for 4 times). - Spam usage patterns in conversation channels. 🛀 Additional notes - The form to be filled out after every suspension/restoration can be accessed here. - The previous suspensions and review information can be seen here.

Reporting scams to Chatwoot

At Chatwoot, we are aware that complaints have been received regarding companies allegedly misusing our platform for fraudulent purposes. We want to clarify that we do not endorse or permit the use of Chatwoot for any deceptive activities whatsoever. Our terms of service unambiguously disallow such misuse of our platform. As an open-source tool, Chatwoot can customized and hosted in services which our team doesn't have access to. Hence, there is a possibility Chatwoot can be misused in ways we didn't envision, and we're aware we can't control every use. However, we're proactive about taking steps against potential misuses. Reporting such instances would help us to keep a record and we will maintain a complete fraud report to help ensure legal compliance in future. We have a firm commitment to enforcing our terms of service, which are clearly stated and shared with all users. This applies irrespective of the user's payment status - whether they are using the free version of Chatwoot Cloud, or are premium paying customers. Any violation of these terms will be met with appropriate action to protect the integrity of our service and the safety of our user community. Please use the form provided below to report fraud. https://forms.gle/rWctn3JBERYWJkxX8