Discussion guidelines#

Autoware uses GitHub Discussions for questions, ideas, feature requests, and design topics. This page explains how to start a discussion and how to take part in one. For the list of all support channels, refer to the support guidelines.

Choose the right place#

Use GitHub Discussions for topics that are not yet confirmed bugs or tasks. Use GitHub Issues only for confirmed bugs and confirmed tasks. If an issue is a question or an unconfirmed bug, the maintainers can move it to Discussions.

The discussions of the Autoware Foundation organization have these categories:

Before you start a discussion#

1. Search the documentation and the troubleshooting pages for your problem.
2. Search the existing discussions and the issues of the related repositories. The autoware.repos file lists the repositories.
3. If you find a discussion about the same topic, add your information to it. Do not start a new one.

Start a discussion#

The General category uses a form. The form asks you to confirm that you read the Code of Conduct and the support guidelines. Then you write your post in the Contents field. The other categories have a plain text box.

Write a post that other people can answer without asking for more information:

• Write a title that tells the problem or the proposal in one line. For example, "EKF localizer diverges after the vehicle stops" is better than "Help with localization".
• Write what you want to do, what you did, what you expected, and what happened.
• Give the version of Autoware (for example 2.0.0 or the commit of main), the ROS 2 distribution, the operating system, and how you installed Autoware (source or Docker).
• Give the steps to reproduce the problem. Use the smallest setup that shows it, for example the planning simulator with the sample map.
• Put commands, logs, and error messages in code blocks. Do not post screenshots of text.
• Add screenshots or videos only for things that text cannot show, for example a view in RViz.
• Write one topic per discussion. If you have two unrelated questions, start two discussions.

For a feature request or an idea, also write:

• The problem that the feature solves and who has this problem.
• The solution that you propose, and the other solutions that you considered.
• Whether you plan to implement it yourself.

Take part in a discussion#

• Follow the Code of Conduct. Be respectful, also when you disagree.
• Reply in the thread of the comment that you answer, so that the conversation stays easy to follow.
• Give reasons and evidence for your opinion, for example logs, measurements, or links to code.
• Write in English, so that the whole community can read and search your post. You can use machine translation for text that you wrote yourself.
• Follow the AI contribution policy. Your own words carry the conversation, and you must mark AI-generated material as such.
• Do not mention many people only to get attention. Mention the people or teams that can help with the topic.

Close a discussion#

• In Q&A, Feature requests, and Ideas, mark the comment that answers your question as the answer. This helps other people who have the same problem.
• If you found the solution yourself, post it in the discussion and mark it as the answer.
• If you get no reply within a week, mention @autoware-maintainers in a comment to remind them.

From a discussion to an issue and a pull request#

A discussion is the first step of a larger change:

1. A discussion confirms a bug, or the community and the maintainers agree on a proposal.
2. A maintainer or the author creates an issue from the discussion in the related repository.
3. A contributor makes a pull request that refers to the issue. Refer to the pull request guidelines.

For more details on this process, refer to How can I contribute?.

Further reading#

• GitHub Docs: Best practices for community conversations on GitHub
• Open Source Guides: Communicating effectively