feat(support-guidelines): update guidelines for Autoware community su…

…pport (autowarefoundation#578) Signed-off-by: M. Fatih Cırıt <[email protected]>
tier4 · Jun 24, 2024 · 0bcd252 · 0bcd252
1 parent 752f452
commit 0bcd252
Showing 1 changed file with 85 additions and 23 deletions.
diff --git a/docs/support/support-guidelines.md b/docs/support/support-guidelines.md
@@ -10,19 +10,53 @@ This page explains the support mechanisms we provide.
 Choose appropriate resources depending on what kind of help you need and read the detailed description in the sections below.
 
 - [Documentation sites](#documentation-sites)
-  - Various information
+  - Gathering information
 - [GitHub Discussions](#github-discussions)
-  - Questions
-  - Unconfirmed bugs
-  - Feature requests
-  - Design discussions
+  - Questions or unconfirmed bugs -> [Q&A](https://github.com/orgs/autowarefoundation/discussions/categories/q-a)
+  - [Feature requests](https://github.com/orgs/autowarefoundation/discussions/categories/feature-requests)
+  - [Design discussions](https://github.com/orgs/autowarefoundation/discussions/categories/design)
 - [GitHub Issues](#github-issues)
   - Confirmed bugs
+  - Confirmed tasks
 - [Discord](#discord)
   - Instant messaging between contributors
 - [ROS Discourse](#ros-discourse)
   - General topics that should be widely announced
 
+## Guidelines for Autoware community support
+
+If you encounter a problem with Autoware, please follow these steps to seek help:
+
+### 1. Search for existing Issues and Questions
+
+Before creating a new issue or question, check if someone else has already reported or asked about the problem. Use the following resources:
+
+- **[Issues](https://github.com/autowarefoundation/autoware/issues)**
+
+  Note that Autoware has multiple repositories listed in [autoware.repos](https://github.com/autowarefoundation/autoware/blob/main/autoware.repos).
+  It is recommended to search across all repositories.
+
+- **[Questions](https://github.com/autowarefoundation/autoware/discussions/categories/q-a)**
+
+### 2. Create a new question thread
+
+If you don't find an existing issue or question that addresses your problem, create a new question thread:
+
+- **[Ask a Question](https://github.com/autowarefoundation/autoware/discussions/categories/q-a)**
+
+  If your question is not answered within a week, mention `@autoware-maintainers` in a post to remind them.
+
+### 3. Participate in other discussions
+
+You are also welcome to open or join discussions in other categories:
+
+- **[Feature requests](https://github.com/autowarefoundation/autoware/discussions/categories/feature-requests)**
+- **[Design discussions](https://github.com/autowarefoundation/autoware/discussions/categories/design)**
+
+### Additional resources
+
+If you are unsure how to create a discussion, refer to the [GitHub Docs on creating a new discussion](https://docs.github.com/en/discussions/quickstart#creating-a-new-discussion).
+
 ## Documentation sites
 
 [Docs guide](docs-guide.md) shows the list of useful documentation sites.
@@ -31,39 +65,67 @@ Visit them and see if there is any information related to your problem.
 Note that the documentation sites aren't always up-to-date and perfect.
 If you find out that some information is wrong, unclear, or missing in Autoware docs, feel free to submit a pull request following the [contribution guidelines](../contributing/index.md).
 
+## GitHub Discussions
+
+[GitHub discussions page](https://github.com/orgs/autowarefoundation/discussions) is the primary place for asking questions and discussing topics related to Autoware.
+
+| Category                                                                                                               | Description                                                             |
+| :--------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------- |
+| [Announcements](https://github.com/orgs/autowarefoundation/discussions/categories/announcements)                       | Official updates and news from the Autoware maintainers                 |
+| [Design](https://github.com/orgs/autowarefoundation/discussions/categories/design)                                     | Discussions on Autoware system and software design                      |
+| [Feature requests](https://github.com/orgs/autowarefoundation/discussions/categories/feature-requests)                 | Suggestions for new features and improvements                           |
+| [General](https://github.com/orgs/autowarefoundation/discussions/categories/general)                                   | General discussions about Autoware                                      |
+| [Ideas](https://github.com/orgs/autowarefoundation/discussions/categories/ideas)                                       | Brainstorming and sharing innovative ideas                              |
+| [Polls](https://github.com/orgs/autowarefoundation/discussions/categories/polls)                                       | Community polls and surveys                                             |
+| [Q&A](https://github.com/orgs/autowarefoundation/discussions/categories/q-a)                                           | Questions and answers from the community and developers                 |
+| [Show and tell](https://github.com/orgs/autowarefoundation/discussions/categories/show-and-tell)                       | Showcase of projects and achievements                                   |
+| [TSC meetings](https://github.com/orgs/autowarefoundation/discussions/categories/tsc-meetings)                         | Minutes and discussions from TSC(Technical Steering Committee) meetings |
+| [Working group activities](https://github.com/orgs/autowarefoundation/discussions/categories/working-group-activities) | Updates on working group activities                                     |
+| [Working group meetings](https://github.com/orgs/autowarefoundation/discussions/categories/working-group-meetings)     | Minutes and discussions from working group meetings                     |
+
 !!! warning
 
-    Since this documentation site is still under construction, there are some empty pages.
+    GitHub Discussions is not the right place to track tasks or bugs. Use GitHub Issues for that purpose.
 
-## GitHub Discussions
+## GitHub Issues
 
-If you encounter a problem with Autoware, check existing issues and questions and search for similar issues first.
+GitHub Issues is the designated platform for tracking confirmed bugs, tasks, and enhancements within Autoware's various repositories.
 
-- [Issues](https://github.com/autowarefoundation/autoware/issues)
+Follow these guidelines to ensure efficient issue tracking and resolution:
 
-  Note that Autoware has multiple repositories listed in [autoware.repos](https://github.com/autowarefoundation/autoware/blob/main/autoware.repos).  
-  It is recommended to search across the repositories.
+### Reporting bugs
 
-- [Questions](https://github.com/autowarefoundation/autoware/discussions/categories/q-a)
+If you encounter a confirmed bug, please report it by creating an issue in the appropriate Autoware repository.
+Include detailed information such as steps to reproduce, expected outcomes, and actual results to assist maintainers in addressing the issue promptly.
 
-If no answer was found, create a new question thread [here](https://github.com/autowarefoundation/autoware/discussions/categories/q-a).
-If your question is not answered within a week, then @mention the maintainers to remind them.
+### Tracking tasks
 
-Also, there are other discussion types such as [feature requests](https://github.com/autowarefoundation/autoware/discussions/categories/feature-requests) or [design discussions](https://github.com/autowarefoundation/autoware/discussions/categories/design).
-Feel free to open or join such discussions.
+GitHub Issues is also the place for managing tasks including:
 
-If you don't know how to create a discussion, refer to [GitHub Docs](https://docs.github.com/en/discussions/quickstart#creating-a-new-discussion).
+- **Refactoring:** Propose refactoring existing code to improve efficiency, readability, or maintainability. Clearly describe what and why you propose to refactor.
+- **New Features:** If you have confirmed the need for a new feature through discussions, use Issues to track its development. Outline the feature's purpose, potential designs, and its intended impact.
+- **Documentation:** Propose changes to documentation to fix inaccuracies, update outdated content, or add new sections. Specify what changes are needed and why they are important.
 
-## GitHub Issues
+### Creating an issue
 
-If you have a problem and you have confirmed it is a bug, find the appropriate repository and create a new issue there.
-If you can't determine the appropriate repository, ask the maintainers for help by creating a new discussion in the [Q&A category](https://github.com/autowarefoundation/autoware/discussions/categories/q-a).
+When creating a new issue, use the following guidelines:
 
-!!! warning
+1. **Choose the Correct Repository**: If unsure which repository is appropriate, start a discussion in the [Q&A category](https://github.com/autowarefoundation/autoware/discussions/categories/q-a) to seek guidance from maintainers.
+2. **Use Clear, Concise Titles**: Clearly summarize the issue or task in the title for quick identification.
+3. **Provide Detailed Descriptions**: Include all necessary details to understand the context and scope of the issue. Attach screenshots, error logs, and code snippets where applicable.
+4. **Tag Relevant Contributors**: Mention contributors or teams that might be impacted by or interested in the issue.
+
+### Linking issues and pull requests
 
-    Do not create issues for questions or unconfirmed bugs. If such issues are created, maintainers will transfer them to GitHub Discussions.
+When you start working on an issue, link the related pull request to the issue by mentioning the issue number.
+This helps maintain a clear and traceable development history.
+
+For more details, see the [Pull Request Guidelines page](../contributing/pull-request-guidelines/index.md).
+
+!!! warning
 
-If you want to fix the bug by yourself, discuss the approach with maintainers and submit a pull request.
+    GitHub Issues is not for questions or unconfirmed bugs. If an issue is created for such purposes,
+    it will likely be transferred to GitHub Discussions for further clarification.
 
 ## Discord