From 729743b72fab894710e6dd2f1f76aa0814e33f54 Mon Sep 17 00:00:00 2001 From: sarahfarnborough-3di Date: Sat, 1 Aug 2026 05:53:26 +0100 Subject: [PATCH] Create contributing to ros (#6918) * Adding structure and content for first draft, and adding topic to TOC * Adding content to first draft * Adding content to first draft * create-contributing-to-ros * Update contributing to ROS * Update Contributing to ROS and Contact article * Peer review changes to draft3 * Peer review changes to contact draft 2 * Final peer review changes to contact * Fix email links in contact * update links and apply peer review comments * updates following peer review * Add newlines after headings * delete whitespace and add newlines * fix lint errors and update links * Fixing duplicate and broken links * Apply SME edits * Apply SME edits * Apply SME edits * Avoid duplicate link label Signed-off-by: Geoffrey Biggs * Slight wording clarification Signed-off-by: Geoffrey Biggs --------- Signed-off-by: Geoffrey Biggs Co-authored-by: Denise Marshall Co-authored-by: Geoffrey Biggs Co-authored-by: Keith Kirkwood (cherry picked from commit ca528b86ae4725bb96f47f2202000f90b032f7b1) # Conflicts: # source/Contact.rst --- source/Contact.rst | 160 +++++++++------ source/Contributing-To-ROS.rst | 346 +++++++++++++++++++++++++++++++++ source/index.rst | 6 +- 3 files changed, 449 insertions(+), 63 deletions(-) create mode 100644 source/Contributing-To-ROS.rst diff --git a/source/Contact.rst b/source/Contact.rst index 1e3acca25fa..262467773cb 100644 --- a/source/Contact.rst +++ b/source/Contact.rst @@ -1,38 +1,56 @@ -.. _Help: - Contact ======= -.. _Using Robotics Stack Exchange: +Contact the ROS community to ask for support, offer help, or suggest ways we can improve. +This article introduces the ways in which you can contact us. + +**Area: community | content-type: about | experience: beginner, intermediate, expert** + +.. contents:: Table of Contents + :local: -Support +Summary ------- -Different types of questions or discussions correspond to different avenues of communication; -check the descriptions below to ensure you choose the right method. +You can contact the ROS community in the following ways: + +* `Stack Exchange `__: Ask for support or discuss a problem + +* Issue tracker: Submit an issue or suggest an enhancement: + +* :ref:`Discourse discussion boards `: Share ideas or discuss best practices + +* `Zulip chat `_: Chat to other ROS community members, including maintainers, in real time in the ``General`` or ``ROS General`` topics. + +* `Email `_: Contact us directly if you have a private or sensitive issue + +* `Email (security) `_: Contact us directly if you have a security concern + +.. _asking-for-support: + +Asking for support +------------------ Need help troubleshooting your system? -First, search `Robotics Stack Exchange `__ to see if others have had similar issues, and if their solution works for you. +First, search `Robotics Stack Exchange `__ to see if others have had similar problems, and if their solution works for you. If not, ask a new question on `Robotics Stack Exchange `__. -Make sure to add tags, at the very least the ``ros2`` tag and the distro version you are running, e.g. ``{DISTRO}``. -If your question is related to the documentation here, add a tag like ``docs``, or more specifically, ``tutorials``. - +Make sure to add tags, at the very least the ``ros`` tag and the distro version you are running, for example, ``{DISTRO}``. +If your question relates to the documentation, add a ``docs`` tag. +You can also add a tag for the relevant documentation area, for example, ``tutorials`` or ``concepts``. Please don't contact the developers/maintainers directly. -The community can't see question or answer(s) not asked or answered publicly. +The community can't benefit from private answers and questions. +Keep your questions out in the public to help others with solving their problems. Open Source development works best when the entire community participates in discussions and helps to answer questions. -It's better to send all questions to `Robotics Stack Exchange `__ and report all issues to the issue tracker. -Contributing support -^^^^^^^^^^^^^^^^^^^^ +.. note:: If you can provide support to others, please do: -ROS 2 users come from a wide range of technical backgrounds, use a variety of different operating systems, and don't necessarily have any prior experience with ROS (1 or 2). -So, it's important for users with any amount of experience to contribute support. +.. _reporting-an-issue: -If you see an issue on `Robotics Stack Exchange `__ that is similar to something you've run into yourself, please consider providing some pointers to what helped in your situation. -Don't worry if you aren't sure if your response is correct. -Simply say so, and other community members will jump in if necessary. +Reporting an issue or suggesting an enhancement +----------------------------------------------- +<<<<<<< HEAD Issues ------ @@ -79,61 +97,83 @@ As appropriate, also include your: * Gifs or movies to demonstrate the problem .. _Using ROS Discourse: +======= +If you identify issues, have suggestions for enhancements, or have a question specific to one package, you can report an issue on GitHub. +>>>>>>> ca528b8 (Create contributing to ros (#6918)) + + + +.. note:: + + If you have a private or sensitive matter to discuss, email us directly at `ros@openrobotics.org `__. + If you have a security concern, email us directly at `security@openrobotics.org `__. + +.. _discussion-boards: -Discussion ----------- +Discussing ideas and best practices +----------------------------------- -To start a discussion with other ROS 2 community members, visit the official `Open Robotics Discourse `__. -Content on the Discourse should be high-level; -it's not a place to get *questions* about code answered, but it would be suitable to start a conversation about best practices or improving standards. +To start a discussion with other ROS community members, visit the official `Open Robotics Discourse `_. +Content on Discourse should be discussions and announcements. +It is not a place to get *questions* about code answered, but it would be suitable to start a conversation about new ideas, best practices, and improving standards. -Discussions about ROS 2 development and plans are happening on the `Open Robotics Discourse' ROS category `__. -Participating in these discussions is an important way to have a say on how different features of ROS 2 will work and be implemented. +Discussions about ROS development and plans are also happening on the `Open Robotics Discourse' ROS category `_. +Discussions about ROS are in the `ROS category `_. +Participating in these discussions is an important way to have a say on how different features of ROS will work and be implemented. The diverse community behind the ROS ecosystem is one of its greatest assets. -We encourage all members of the ROS community to participate in these design discussions so that we can leverage the experience of community members, and keep the varied use cases of ROS in mind. +We encourage all members of the ROS community to participate in these design discussions so that we can leverage the experience of community members, and keep the varied use cases of ROS in mind when design decisions are made. -Etiquette ----------- +Offering help +------------- + +If you are in a position to support others, share your knowledge and help fellow users work through challenges. + + -Assume 'good faith': It's easy to mis-interpret the meaning or tone of comments on the internet. -Assuming good faith gives the benefit of the doubt to those trying to help you, avoiding: insulting well meaning community members, and poisoning the mood. -Assuming 'good faith' when responding almost always works better even if the original response was not in fact in good faith. +Contacting us privately +----------------------- -Please don't send your question more than once: The question was seen. -If you didn't get a response then likely nobody has had time to answer you. -Alternatively, it could be that nobody knows the answer. -In any case, sending it again is poor form and akin to shouting and is likely to aggravate a large number of people. -This also applies to crossposting. -Try to pick the forum which you think matches best and ask there. -If you are referred to a new forum, provide a link to the old discussion. +If you'd like to contact us privately, for example, if your question contains information sensitive to your organization or project, you can email us directly at `ros@openrobotics.org `__. +If your message is regarding a security issue, email `security@openrobotics.org `__. + +Etiquette +--------- -On `Robotics Stack Exchange `__ you can edit your question to provide more details. -The more details that you include in your question the easier it is for others to help you find your solution which makes it more likely for you to get a response. +* Assume 'good faith': It's easy to mis-interpret the meaning or tone of comments on the internet. + Assuming good faith gives the benefit of the doubt to those trying to help you, avoiding insulting well-meaning community members and poisoning the mood. + Assuming 'good faith' when responding almost always works better, even if the original response was not actually in good faith. -It's considered bad form to list your personal deadlines; community members answering questions also have them. +* Please don't send your question more than once: The question was seen. + If you didn't get a response then likely nobody has had time to answer you. + Alternatively, it could be that nobody knows the answer. + In any case, sending it again is poor form and akin to shouting and is likely to aggravate a large number of people. + This also applies to cross-posting. + Try to pick the forum which you think matches best and ask there. + If you are referred to a new forum, provide a link to the old discussion. -Do not beg for help. -If there is someone willing and able to help with your problem, you usually get a response. -Asking for faster answers will mostly have a negative effect. +* On `Robotics Stack Exchange `__ , you can edit your question to provide more details. + The more details that you include in your question, the easier it is for others to help you find your solution which makes it more likely for you to get a response. -Do not add unrelated content to posts. -The content of posts should be focused on the topic at hand and not include unrelated content. -Content, links, and images unrelated to the topic are considered spam. +* It's considered bad form to list your personal deadlines. + Community members answering questions also have them. -For commercial posts, see also `this discussion `_. +* Do not beg for help. + If there is someone willing and able to help with your problem, you usually get a response. + Asking for faster answers will mostly have a negative effect. -Minimize references to content behind pay walls. -The content posted on `Open Robotics Discourse `__ and `Robotics Stack Exchange `__ should "generally" be free and open to all users. -Links to content behind pay walls such as private journal articles, text books, and paid news websites, while helpful and relevant, may not be accessible to all users. -Where possible primary sources should be free and open with paid content playing a supporting role. +* Do not add unrelated content to posts. + The content of posts should be focused on the topic at hand and not include unrelated content. + Content, links, and images unrelated to the topic are considered spam. -Single link posts are to be avoided. -Generally speaking, posting a single link answer is less helpful and can be easily confused with spam. -Moreover, links may degrade over time or be replaced. -Paraphrasing a link's content along with some contextual information and attribution is often much more helpful. +* For commercial posts, see also `this discussion `_. -Private contact ---------------- +* Minimize references to content behind pay walls. + The content posted on Open Robotics Discourse and Robotics Stack Exchange should be free and open to all users. + Links to content behind pay walls such as private journal articles, text books, and paid news websites, while helpful and relevant, may not be accessible to all users. + Where possible primary sources should be free and open with paid content playing a supporting role. -If you'd like to contact us privately (e.g., if your question contains information sensitive to your organization or project, or if it's regarding a security issue), you can email us directly at ``ros@osrfoundation.org``. +* Single link posts are to be avoided. + Generally speaking, posting a single link answer is less helpful and can be easily confused with spam. + Moreover, links may degrade over time or be replaced. + Paraphrasing a link's content along with some contextual information and attribution is often much more helpful. diff --git a/source/Contributing-To-ROS.rst b/source/Contributing-To-ROS.rst new file mode 100644 index 00000000000..119aa23fa86 --- /dev/null +++ b/source/Contributing-To-ROS.rst @@ -0,0 +1,346 @@ +Contributing to ROS +=================== + +ROS (Robot Operating System) is an open-source ecosystem. +We rely on contributions from our community to help us grow and improve. +This article introduces the ways in which you can contribute to ROS. + +**Area: contributing, community | Content-type: about | Experience: beginner, intermediate, expert** + +.. contents:: Table of Contents + :local: + +Summary +------- + +ROS is an open source, federated collection of tools and libraries that is built through contributions from our community. +Whether you are a developer, researcher, company, or student, your contribution helps us to grow and improve. + +Your first contribution +----------------------- + +Everyone can contribute to ROS. +Depending on your skills and experience, you can review and update the ROS documentation, contribute code, fix issues, review code submitted by others, participate in design discussions, and help others learn to use ROS or overcome their problems. + +**Complete beginner?** + +* Work through the beginner tutorials, and check them for accuracy or improve explanations. + + :ref:`See Test and review documentation ` + +**Getting familiar with ROS?** + +* Check the issue lists and fix one of the issues labelled "good first issue". + + :ref:`See Contribute to code ` + +* Triage an issue. + + :ref:`See Triage an issue ` + +**Experienced robotics developer?** + +* Watch for questions on Robotics Stack Exchange, and offer support. + + :ref:`See Provide support ` + +* Review code submitted by others, to help improvements and bug fixes get merged faster for the benefit of everyone. + + :ref:'`See Review a code pull request ` + +Contribute to ROS development +----------------------------- + +Anyone can contribute to the development of ROS. +If you are a complete beginner looking for an entry point, start with a simple contribution such as fixing a small issue from the `Good first issues list `_ +If you are a more experienced developer, consider contributing at a deeper level by designing new features, reviewing code from other developers, or fixing +complex bugs. + +.. _review-code: + +Review a code pull request +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Reviewing a pull request involves carefully checking proposed changes to make sure they are correct, well written, and do not introduce issues. +Anyone can review a pull request. +If you are a beginner, reviewing a pull request is a great way to learn the codebase and ask questions where something is unclear. +If you are a more experienced developer, you can contribute by identifying design, performance, or security issues and ensuring overall code quality. + +.. _contribute-to-code: + +Contribute to code +~~~~~~~~~~~~~~~~~~ + +Contributing to our open source code involves reviewing an existing project and making improvements such as fixing bugs, improving issues, or developing features. + +**Ready to contribute?** + +1. Familiarize yourself with our developer guidelines and tools. + + `More information is in our developer guide `_ + +2. Pick an issue from one of the issue lists: + + * `Good first issues `_ + + * `Help wanted issues `_ + +3. Fix the issue and submit the pull request. + + More information is in + +**Ready to contribute?** + +1. Familiarize your with how to review a pull request. + + More information is in . + +2. Pick an issue from the pull request list: `Pull request list `_ + +Contribute to QA +~~~~~~~~~~~~~~~~~ + +.. _triage-an-issue: + +Triage an issue +^^^^^^^^^^^^^^^ + +Triaging an issue involves reviewing the reported issue to understand the problem, assess its impact, and decide what action to take next. +If you are a beginner, you can help by checking whether an issue can be reproduced and providing additional details where needed. +If you are a more experienced contributor, you can prioritize issues, identify root causes, and guide how and when they should be resolved. + +**Ready to contribute?** + +1. Pick an issue to triage: + + * `General ROS issue tracker `_ + +2. Triage the issue. + + More information is in + +Report an issue +^^^^^^^^^^^^^^^ + +Reporting issues involves identifying and describing problems in the software so they can be understood and fixed. +You can report any issues you encounter with information to help developers quickly diagnose and resolve the issue. +If you are a beginner following a tutorial, for example, you can include the steps needed to reproduce the problem. +If you are a more experienced contributor, you can also provide relevant technical details. + +**Ready to contribute?** + +* Report your first issue. + +More information is in + +Report security vulnerabilities +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Reporting security vulnerabilities involves responsibly identifying and disclosing potential security issues so they can be safely addressed and resolved. + +If you spot a security vulnerability, contact security@openrobotics.org + +Contribute to future design +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Contributing to design involves shaping how features are structured and interact, ensuring they are intuitive, scalable, and aligned with user needs. + +Join a discussion +^^^^^^^^^^^^^^^^^ + +Taking part in discussions involves contributing ideas and feedback about how features and systems can be designed and improved. +Every contribution is valuable, even small questions or suggestions. +If you are a more experienced contributor, you can help shape design decisions, evaluate different approaches, and guide the overall direction of the project. + +**Ready to contribute?** + +* Join an ongoing discussion, and share your thoughts: `Open Robotics Discourse `_ + +Suggest a feature +^^^^^^^^^^^^^^^^^ + +ROS continues to evolve, and suggesting features is a valuable way to help improve the experience for everyone. +If you spot a way that ROS can be improved, you can post about it to get feedback from the community on its validity. +If your idea is significant enough, it may even be worth making a `Robotics Enhancement Proposal `_ for it. +Don't forget to check the existing list of requests first! + +**Ready to contribute?** + +1. Check if the enhancement has already been suggested: + + * `ROS Ideas category at Discourse `_ + + * `Future ROS releases idea list `_ + + * Enhancement issues on GitHub. + For example, take a look at the project list, where you can `view project enhancement requests `_ + +2. Talk to the community about your suggested enhancement in the `ROS Ideas category at Discourse `__ + +3. Submit an enhancement suggestion as an issue on the appropriate repository, or, for more significant ideas (and when recommended to do so in discussion about your idea), `submit a new REP `_ + + More information on submitting an issue is in . + +Improve graphical interfaces +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +ROS includes a number of graphical interfaces. +Anyone can suggest interface improvements, especially those with UX design experience. +This helps to shape a more intuitive and user-friendly design. + +**Ready to contribute?** + +* Submit a UI improvement, for example, your suggestion or your design work. + + More information is in + +* Implement a UI improvement. + + :ref:`See Contribute to code ` + +Become a project member (maintainer) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +ROS maintainers ensure that the project is making progress. +The responsibilities of maintainers include: + +* Reviewing incoming code contributions for style, quality, and overall fit into the goals of the repository and ROS + +* Ensuring that CI continues to stay green + +* Merging pull requests that meet the quality and CI standards + +* Addressing issues opened up by users + +A maintainer is responsible for guiding development, reviewing contributions, and helping ensure the quality and direction of ROS. +At ROS, there are two maintainer roles: as a Committer, or as a Project Management Committee (PMC) Member. +All PMC Members are also Committers. +A Committer can merge pull requests, while a PMC Member helps guide the overall direction and governance of the project. + +**Ready to contribute?** + +Each core repository in the ROS project has Committers who are responsible for that repository. +Becoming a new Committer of one or more of those repositories is a process based on mentorship. +The process begins with an existing PMC Member inviting you to be mentored, or you volunteering and finding a PMC Member willing to mentor you. +For full and current details of the process, please see the `ROS Project Charter `_ +Generally, you will need to have demonstrated a sustained period of making contributions such as reviewing PRs and submitting PRs before someone is likely to invest time into mentoring you. +Approximately every 3 months, the ROS team will review the contributions in all of the repositories and send out invitations to new maintainers. +Once the invitation is accepted, the new maintainer will be asked to go through a short training process on the mechanisms and policies of the ROS repositories. +After that training process is completed, the new maintainer will be given write access to the appropriate repositories. + +* Guidance for maintainers: `ROS Core Maintainer Guide `_ + +Contribute to documentation +--------------------------- + +Contribute to improving and expanding the ROS documentation. + +Review a documentation pull request +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Reviewing a pull request involves carefully checking proposed documentation changes to make sure the content is clear and correct. +Anyone can review a pull request. +Reviewing a pull request is a great way to learn about ROS and ask questions where something is unclear. + +Write and update documentation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Contributing to the ROS documentation is a great way to learn about and improve ROS. +Writing and updating documentation ensures it stays aligned with the code. +Whenever you update the code, you should also update the documentation so that it remains accurate and reliable. +Anyone can help with maintaining the existing documentation. +If you are a beginner, you can help by fixing small issues such as typos or unclear instructions. +More experienced contributors can improve and expand documentation. + +**Ready to contribute?** + +1. Read our documentation contribution guidelines: . + +2. Browse the documentation issue list, and choose an issue to fix: `ROS documentation issue tracker `_ + +3. Update the documentation to fix the issue. + + More information is in . + +.. _test-and-review-documentation: + +Test and review documentation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Testing and reviewing documentation makes sure it is clear, accurate, and easy to follow in practice. +It involves checking that instructions work as expected and reflect how the code behaves. +If you are a beginner, you can follow our tutorials and how-to guides and report anything that is unclear or incorrect. +If you are a more experienced contributor, you can validate technical accuracy, identify gaps, and improve the overall structure and clarity. + +**Ready to contribute?** + +* Follow a tutorial, how-to guide, or other documentation. + If you spot something inaccurate or unclear, provide your feedback. + + More information is in + +.. _provide-support: + +Provide support +--------------- + +ROS users come from a wide range of technical backgrounds and use different operating systems. +Some are completely new to ROS, so even those with a little experience can play an important role in supporting others as they get started. + +If you notice a question on `Robotics Stack Exchange `_ that relates to an issue you have encountered, consider sharing what worked for you. +If you aren't entirely sure your answer is correct, just say so. +The community is there to help, and others will step in to clarify or add more detail if needed. +Helping others is also one of the fastest and most effective ways to improve your own ROS knowledge. +Even if you don't know the answer to someone's question immediately, try finding a solution, and when you have one, post that as an answer to the question. + +**Ready to contribute?** + +* Provide pointers on Robotics Stack Exchange: `Robotics Stack Exchange `_ + +* Chat with new community members by visiting the official Open Robotics Discourse: `Open Robotics Discourse `__ + +Participate in the community +---------------------------- + +There are various ways to join the ROS community, allowing you to participate, collaborate, and contribute effectively. +Here are some ways you can join in: + +* Attend events, from local informal meetings to our annual developer conference, `ROSCon `_: + + * Community organized events: `View the calendar `__ + + * Official Open Robotics events: `View the calendar `__ + +* Host an online community group event: `Fill in the form to add your event to the calendar `_ + + You can also ask for help with hosting an event on `Zulip `_ or `Discourse `_ + +* Host a local meet-up: `Fill in the form to add your event to the calendar `_ + + (Help with hosting local meet-up link to be provided) + +* Join discussion groups and chats: + + * `Discussions `_ + + * `Developer chat `_ + +Promote ROS +----------- + +If you want to get involved in promoting ROS, why not train or mentor others, or host a meetup in your area. + +**Ready to contribute?** + +* Support people with working through the tutorials, starting with `First steps with ROS `_ + +* Be part of our community on social media: + +Become an OSRA member +--------------------- + +Becoming an OSRA member lets you influence the organization's direction, collaborate with a wider community, and contribute more directly to the growth and impact of our projects. + +`Learn more about OSRA `_ and about `becoming a member `_ diff --git a/source/index.rst b/source/index.rst index 94f6661eb4a..7ccf55efea0 100644 --- a/source/index.rst +++ b/source/index.rst @@ -22,7 +22,7 @@ ROS 2 Documentation Related-Projects Glossary Citations - + Contributing-To-ROS **The Robot Operating System (ROS) is a set of software libraries and tools for building robot applications.** From drivers and state-of-the-art algorithms to powerful developer tools, ROS has the open source tools you need for your next robotics project. @@ -117,12 +117,12 @@ If you need help, have an idea, or would like to contribute to the project, plea * `Robotics Stack Exchange - community Q&A website `__ (ROS 1, ROS 2) - - See :ref:`Contact Page ` for more information + - See the :doc:`Contact Page ` for more information * `Open Robotics Discourse `__ (ROS 1, ROS 2) - Forum for general discussions and announcements for the ROS community - - See the :ref:`Contact Page ` for more information + - See the :doc:`Contact Page ` for more information * `ROS Index `__ (ROS 1, ROS 2)