From c13482d81245ee2c2ae3c7e1b08083f919546aa2 Mon Sep 17 00:00:00 2001 From: Geoffrey Biggs <709167-gbiggs@users.noreply.gitlab.com> Date: Fri, 22 May 2020 06:35:54 +0000 Subject: [PATCH 01/12] docs: copy documents from Autoware.Auto Reorganize documentation structure Signed-off-by: Geoffrey Biggs [#499] Adding note in developers guide about double-star syntax. Squashed 'src/external/mpc/' changes from 8fc7cfdd..eaa5908b eaa5908b Merge branch 'input-weight-modify' into 'master' b9ee8e4f Update default mpc_controller_node parameters 8d15f49d Add weights to acceleration and steer controls; loosen simulation test case: git-subtree-dir: src/external/mpc git-subtree-split: eaa5908bdd987051a9dcd9c505f99bfd7f028547 unify coverage instructions Add design doc for autoware_auto_create_pkg Resolve "Remove Atom from ADE" Squashed 'src/external/autoware_auto_msgs/' changes from 56550efd..f40970ea f40970ea Adding velocity_mps to VehicleControlCommand. git-subtree-dir: src/external/autoware_auto_msgs git-subtree-split: f40970ead34d36a695b432dc37accff9d67c17e2 Resolve "Add Notes about Doc Format to Contribution Guide" [!801] Expand contributor guidelines and associated documents - Explain stable links and polish documentation.md - Synchronize links from merge request template to contributor guide - Update coverage, unit test, integration test commands - Remove short paragraphs about unit and integration test from contributer guidelines because there are dedicated sections for that - Add images to show how to find coverage report in CI - Require first commit to have proper message - rewrote "how to run exectable" section because it wasn't rendered nicely Move/retitle a few files Reorganize building & other sections Reviewer comments [!821] Fix numerours code highlighting and markup issues, add TOCs - TOC still missing on design docs [!835] Add AVP instructions to docs Other improvements of the docs include - table-of-contents generation fixed - replace links to external markdown files with HTML. Not sure why doxygen doesn't complain in CI, it failed with version 1.8.13 in my ADE - spell checking of numerous documents - remove subtree doc [#912] Make code snippet blocks consistent in documentation [#924] Use `#` in commit msg tag - Update prepare-commit-msg git hook - update MR templates - update contributor guidelines [#813] use autoware_set_compile_options() for nearly all compiled tests - fix a few causes of warnings and disable warning flags as needed for other tests - set CXX_STANDARD strictly and only in a single place - add CMake flag `AUTOWARE_OPTIMIZATION_OF_SLOW_TARGETS`. Default: OFF - update building instructions and MR template - fix nasty initialization error of static constexpr member in `GenericState` of Kalman filter [#954] Clarify copyright notice [1007] Fix up Doxygen format to work around old Doxygen version failing to link to .md files [#920] Add changes for review workflow [#949] Update docs on integration testing [!960] Remove rtd workarounds [#1012] Update contributor guidelines with merge-bot info [#1109] Explain merge bot and MR title in MR templates [#1319] Add a .clang-format file to Project Root --- .../contributors-guidelines.md | 394 ++++++++++++++++++ 1 file changed, 394 insertions(+) create mode 100644 docs/contributors_guide/contributors-guidelines.md diff --git a/docs/contributors_guide/contributors-guidelines.md b/docs/contributors_guide/contributors-guidelines.md new file mode 100644 index 00000000000..e1dd7f4c890 --- /dev/null +++ b/docs/contributors_guide/contributors-guidelines.md @@ -0,0 +1,394 @@ +Guidelines and Best Practices {#contributor-guidelines} +=========== + +@tableofcontents + +# Contribution Workflow + +1. [Create an issue](https://gitlab.com/autowarefoundation/autoware.auto/AutowareAuto/-/issues/new?issue%5Bassignee_id%5D=&issue%5Bmilestone_id%5D=) defining your intended contribution + 1. Use one of the provided templates [by selecting one from the drop-down list](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates). + 2. Select yourself in the `Assignee` field. + 3. If you have permissions to do so, assign to an appropriate milestone. If you do not have permissions, [mention](https://about.gitlab.com/blog/2016/03/08/gitlab-tutorial-its-all-connected/#mention-others-and-assign) a [maintainer](https://gitlab.com/groups/autowarefoundation/autoware.auto/committers/-/group_members) in the issue for milestone assignment. + 4. The issue template you choose will assign one appropriate label for the issue type (bug, discussion, feature, or improvement). + Assign any additional labels from the available list that you feel are appropriate for the issue's status or other attributes. + +2. Create a fork + 1. For more information about the fork-and-pull model, see the [Develop in a Fork](@ref develop-in-a-fork) page. + +3. Write code + +4. Create a merge request + 1. For more information about the fork-and-pull model, see the [Develop in a Fork](@ref develop-in-a-fork) page. + +5. Finish a merge request + + 1. The review process for the MR is as follows: + 1. Submitter adds Reviewer(s) and assigns herself. + 2. Reviewer reviews and submits comments. + 3. Assignee addresses the reviews making necessary changes and notifies Reviewer(s) to have another look. + 4. Repeat 2 and 3 as necessary. + 5. When Reviewer approves, the MR should be assigned to the `@merge-bot` account which will automatically rebase and merge it. + 2. In order for a merge request to be merged to Autoware.Auto, it must meet the following criteria: + - All discussions on the merge request must be resolved. + - All items of the merge-request checklist are checked off. + - CI jobs for the merge request must have passed successfully. + 3. Once your merge request has been accepted by the reviewer, assign the merge request to the `@merge-bot` account. + + +# Guidelines for General Code Development + +Only C++14 and below is allowed for functional code. +Python 3.7+ and Bash are allowed for tooling. +CMake is the preferred build system, it should integrate with Colcon. +Deviations need to be approved by the maintainers. + +The requirements for C++14 and Python 3.7+ align with compiler and tooling support found in ROS Foxy. +This may change in the future as new OS or ROS environments are targeted; see @ref target-environments for details. + +## License and Copyright +Every file should have a license header; see the *License* section in [CONTRIBUTING.md](https://gitlab.com/autowarefoundation/autoware.auto/AutowareAuto/-/blob/master/CONTRIBUTING.md). + +## Building +See @ref building. + +## Committing {#contributors-guidelines-committing} + +Developers should commit and push regularly to GitLab to avoid data loss. Commit messages should follow +common standards as laid out in this [post](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). In +summary, + +1. Write your commit message in the imperative +1. In the mandatory first line, summarize *what* the functional change is, not *why* it is introduced +1. Optionally add more details separated by a blank line + +As a general recommendation, add a reference to the issue in the commit message so it is easier for others in the future +to get more context about the changes in the commit. If the commit doesn't refer to a particular issue but only touches +a particular package or aspect, add a reference to that. + +Example summary line referring to issue #716: + + [#716] Expand contributor guidelines + +Example summary line without an issue: + + [CI] Disable flaky tests in foo and bar packages + +There is assistance via `git` hooks to help with commit messages. Navigate to `.git/hooks` in the checkout of +Autoware.Auto, then: + +```{bash} +ln -s ../../.git-hooks/prepare-commit-msg # prepend issue number +ln -s ../../.git-hooks/commit-msg # check formatting of commit message +``` +## Cross-platform Compatibility + +It is preferred to use cross-platform solutions for system-level function calls whenever possible. While the C++ +standard library should be used for as many tasks as possible, some functions (such as `std::filesystem`) are not +available in C++14 in cross-platform implementations. This usually means utilizing libraries like +[`asio`](https://think-async.com/Asio/index.html) for networking tasks and [`a std::filesystem +shim`](https://github.com/gulrak/filesystem) for filesystem navigation is preferred to creating platform-specific +implementations. + +## Documentation + +To check that the code is properly documented and all documents are correctly linked, you can run `AutowareAuto/docs/.doxygen/build.py`. +The generated documentation can be found in `AutowareAuto/docs/_build/html/index.html`. +For more details see the [documentation guide](@ref writing-documentation). + +## Formatting {#contributors-guidelines-formatting} + +Autoware.Auto follows ROS recommendations for code style and formatting. See the [Coding Style and Language Versions +entry for C++](https://index.ros.org/doc/ros2/Contributing/Code-Style-Language-Versions/#id3) or the [Coding Style and +Language Versions entry for Python](https://index.ros.org/doc/ros2/Contributing/Code-Style-Language-Versions/#python) +for more information. We enforce these guidelines using linters provided with `ament` as far as possible. All +packages should have the following in their `package.xml` files: + +```{xml} +ament_lint_auto +ament_lint_common +``` + +In addition, the following should be in the package's `CMakeLists.txt` (extended with other tests): + +```{cmake} +if(BUILD_TESTING) + find_package(ament_lint_auto REQUIRED) + ament_lint_auto_find_test_dependencies() +endif() +``` + +In CI, merge requests fail if they introduce improperly formatted code. To avoid that, format the +C++ code locally with + +```{bash} +ament_uncrustify --reformat file.cpp # update single file in place +ament_uncrustify --reformat path/to/pkg_foo # update all C++ source files in package +``` + +With the above CMake setup, run all linters together with all other tests of a package as described in the [Running +Tests](#contributors-guidelines-run-tests) section or run a specific linter; e.g., + +```{bash} +ament_cpplint path/to/pkg_foo +``` + +Tools such as CLion can parse the output of the previous command and provide fast navigation to +offending lines in the code. + +### Using ament_clang_format + +`ament_uncrustify --reformat` is able to format the code to a degree but its results +are generally not enough to pass `ament_cpplint`. To automate the process, +`ament_clang_format` can be used like: +```{bash} +AutowareAuto $ ament_clang_format --config .clang-format --reformat file.cpp +``` + +The configuration is stored in the text file `.clang-format` in the base directory of a source +checkout of Autoware.Auto. + +`ament_clang_format` is available in ADE by default. When working outside of ADE, install it e.g. +with + +```{bash} +sudo apt install ros-${ROS_DISTRO}-ament-clang-format +``` + +A way to use all these three tools is as follows: +-# `ament_clang_format --config AutowareAuto/.clang-format --reformat file.cpp` +-# `ament_uncrustify --reformat file.cpp` +-# `ament_cpplint file.cpp` +-# Fix all reported errors +-# Repeat the previous steps until `ament_uncrustify` and `ament_cpplint` give no more errors. + +#### Order of header includes + +The recommended order of `#include` directives is based on the [google styleguide](https://google.github.io/styleguide/cppguide.html#Names_and_Order_of_Includes) + +-# corresponding file: from `bar.cpp` in package `foo`, that's `#include "foo/bar.hpp"` +-# C system headers; e.g. `#include ` +-# C++ system headers; e.g. `#include ` +-# headers from this or other packages; e.g. `#include "pkg/baz.hpp"` +-# message headers; e.g. `#include "foo/msg/bar.hpp"` + +with headers in each group sorted alphabetically and groups separated by a single blank line. + +In order for automatic grouping and sorting to work: + +-# Use `#include "foo/bar.hpp"` for headers from the same and other packages +-# Use `#include ` with **angle brackets only for C and C++ system headers** +-# Invoke `ament_clang_format` like explained above. + +The resulting order should satisfy `ament_cpplint`. + +@note If cpplint complains about the order of headers, ensure that the delimiters match the above +rules. Example error: + +```console +Found C system header after C++ system header. +``` + +### Utilizing git pre-commit + +To lint the code automatically before each commit, activate the `pre-commit` +[hook](https://gitlab.com/autowarefoundation/autoware.auto/AutowareAuto/-/blob/master/.git-hooks/pre-commit). From the +repository base directory, do: + +```{bash} +cd .git/hooks +ln -s ../../.git-hooks/pre-commit +``` + +## Code Coverage {#contributors-guidelines-coverage} + +For [code coverage](https://en.wikipedia.org/wiki/Code_coverage), we use the popular [GNU tool +`lcov`](http://ltp.sourceforge.net/coverage/lcov.php) for generating statistics about line coverage. For every merge +request, we run our test suite and report the percentage of lines covered. We aim for a 100% line coverage and +continuously improve our test suite to achieve that number. In particular, we do not accept changes that reduce the +coverage value. If a merge request has a lower line coverage than `master`, we will request the contributor to add more +tests. + +The coverage report for the latest successful CI run on the `master` branch is available +[here](https://autowarefoundation.gitlab.io/autoware.auto/AutowareAuto/coverage/index.html). + +Check @ref unit-testing-coverage for details to create that report manually or @ref testing-overview for more information. + +## C++ Resources + +- [cppreference.com](https://en.cppreference.com/w/) +- [C++ Core Guidelines](http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines) + +# Guidelines for ROS Development + +In general, Autoware.Auto follows the [ROS 2 Developer +Guide](https://index.ros.org/doc/ros2/Contributing/Developer-Guide/) for contributions, except where noted. Some special +items of note that are not described in the ROS 2 Developer Guide are listed below. + +## Creating a New Package + +Basic instructions for creating a new ROS 2 package can be found [in this +tutorial](https://index.ros.org//doc/ros2/Tutorials/Colcon-Tutorial/#create-your-own-package). In Autoware.Auto, much of +the boilerplate code can be automatically generated by utilizing the `autoware_auto_create_pkg` tool. + +For more information on using the tool, see \ref autoware_auto_create_pkg-package-design. + +## 2-Tier Development Pattern + +In all but the most trivial utilities, it is best to implement a code pattern with *at least* two tiers of abstraction +which would look something like: + +1. A "core," pure C++ class which performs all basic algorithmic and utility functions which are not ROS-related. + + This class may use ROS utilities such as logging or message structures, but such use must be justified in terms of + why it cannot be done via the class's external interface (e.g. the enclosing node uses information obtained via the + class's external interface to populate log messages). +2. A "ROS Node" or "ROS Component" class which inherits from `rclcpp::Node` or a subclass, handles all ROS-specific + functions. + + This class should instantiate the class defined in 1. and register the node as a + [component](#contributors-guidelines-components), so it can be created with launch files. + +In the rare case that fine-grained control over execution is desired, create a main function in a separate file with a +[ROS Executor](http://docs.ros2.org/foxy/api/rclcpp/classrclcpp_1_1Executor.html#details) to control provision of +execution time of the node in some way (e.g. through calling `spin()`). + +This design pattern helps to promote separation of concerns and code re-use. The core and the ROS node(s) can be +implemented in separate packages; e.g. `foo` and `foo_nodes`. There are some trivial cases where a simple ROS Node that +does not require a "core" are acceptable but these should be the exception, not the rule. + +## Naming in Autoware.Auto + +The [Naming Guidelines](@ref autoware-common-naming-guidelines) provide for standard, reliable naming and namespacing +conventions which should be used in all Autoware.Auto packages. + +## On Topics and Parameters + +In most cases, topics should receive a default name in code and be remapped if needed. Providing topic names as ROS +parameters is an anti-pattern, with few exceptions. + +Required parameters should not have default values but fail during construction if no value is provided. + +### Parameter File Syntax + +To avoid the need to change parameter files based on the namespacing or node name of a node, use the "double-star" +syntax. e.g.: + +```{yaml} +/**: + ros__parameters: + param1: value +``` + +The above parameter file can be passed to any node regardless of namespace or name and the parameters will populate +those of the node if the declared parameters match those in the file. + +## ROS Components {#contributors-guidelines-components} + +As of ROS Dashing, the recommended way to write Nodes in ROS 2 is using Components. +For more information about components and their use, see [the ROS Composition Guide](https://index.ros.org/doc/ros2/Tutorials/Composition/). +To implement your node as a Component, it must conform to the items below (using `ListenerNode` as an example): + +- Must inherit from `rclcpp::Node` or a subclass (such as `rclcpp::LifecycleNode`) +- Must use a single-argument constructor in the form of: + +```{cpp} +namespace composition_example +{ +class ListenerNode: public rclcpp::Node { + ListenerNode(const rclcpp::NodeOptions & options) + : Node("listener", options) + { + ... + } +} +} // namespace composition_example +``` + +- Must contain a registration macro and header in a single translation unit. For example, the following at the bottom of your `cpp` file would suffice: + +```{cpp} +// Insert at bottom of translation unit, e.g. listener_node.cpp +#include +// Use fully-qualified name in registration +RCLCPP_COMPONENTS_REGISTER_NODE(composition_example::ListenerNode) +``` + +- Must compile the components as a shared library and register them in your `CMakeLists.txt` file. +- Must depend on the `rclcpp_components` package. + +### Minimal CMake Example {#contributors-guidelines-minimal-cmake-example} + +The following is a minimal `CMakeLists.txt` file which uses the recommended `ament_cmake_auto` macros, registers a +single component, builds a stand-alone node which uses the component, and exports it as a dependency for downstream +packages. It can be conveniently created by +[`autoware_auto_create_pkg`](https://autowarefoundation.gitlab.io/autoware.auto/AutowareAuto/autoware_auto_create_pkg-package-design.html): + +```{cmake} +cmake_minimum_required(VERSION 3.5) +project(composition_example) + +find_package(ament_cmake_auto REQUIRED) +ament_auto_find_build_dependencies() + +ament_auto_add_library(listener_node SHARED src/listener_node.cpp) +autoware_set_compile_options(listener_node) +rclcpp_components_register_nodes(listener_node "composition_example::ListenerNode") + +ament_auto_add_executable(listener_node_exe src/listener_main.cpp) +autoware_set_compile_options(listener_node_exe) + +if(BUILD_TESTING) + find_package(ament_lint_auto REQUIRED) + ament_lint_auto_find_test_dependencies() +endif() + +ament_auto_package() +``` + +#### Compiler settings +The C++ standard is set in `autoware_auto_cmake.cmake` and becomes available to a package by +depending on the `autoware_auto_cmake` package in `package.xml` as shown below. Compiler options and +warning flags are set per target by calling the function `autoware_set_compile_options(${target})` +defined in `autoware_auto_cmake.cmake` as well. It should be applied to every C++ target and in +general Autoware.Auto code shall not generate warnings. + +In case the warning flags are too strict for example when including external code, they can be selectively deactivated in special cases as follows: + +```{cmake} +autoware_set_compile_options(${target}) +target_compile_options(${target} PRIVATE -Wno-double-promotion) +``` + +### Minimal Package.xml Example {#contributors-guidelines-minimal-package-xml-example} + +The following is a minimal `package.xml` file to go with the above `CMakeLists.txt` example: + +```{xml} + + + + composition_example + 0.0.1 + Example of node composition + The Autoware Foundation + Apache License 2.0 + + ament_cmake_auto + autoware_auto_cmake + + rclcpp + rclcpp_components + + ament_lint_auto + ament_lint_common + + + ament_cmake + + +``` + + +## Resources + +- [rclcpp_components in Dashing Diademata Release Notes](https://index.ros.org/doc/ros2/Releases/Release-Dashing-Diademata/#rclcpp-components) From accb4c0429d97409e76fab9034350f9fb1dda63a Mon Sep 17 00:00:00 2001 From: Keisuke Shima <19993104+KeisukeShima@users.noreply.github.com> Date: Fri, 26 Nov 2021 18:31:44 +0900 Subject: [PATCH 02/12] update documents Signed-off-by: Kenji Miyake --- .../contributors-guidelines.md | 351 ++++++++++++++++ .../contributors-guidelines.md | 394 ------------------ 2 files changed, 351 insertions(+), 394 deletions(-) create mode 100644 docs/contributing/coding-guidelines/contributors-guidelines.md delete mode 100644 docs/contributors_guide/contributors-guidelines.md diff --git a/docs/contributing/coding-guidelines/contributors-guidelines.md b/docs/contributing/coding-guidelines/contributors-guidelines.md new file mode 100644 index 00000000000..d1b8545d37c --- /dev/null +++ b/docs/contributing/coding-guidelines/contributors-guidelines.md @@ -0,0 +1,351 @@ +# Guidelines and Best Practices + +## Contribution Workflow + +1. [Create an issue](https://gitlab.com/autowarefoundation/autoware.auto/AutowareAuto/-/issues/new?issue%5Bassignee_id%5D=&issue%5Bmilestone_id%5D=) defining your intended contribution + + 1. Use one of the provided templates [by selecting one from the drop-down list](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates). + 1. Select yourself in the `Assignee` field. + 1. If you have permissions to do so, assign to an appropriate milestone. If you do not have permissions, [mention](https://about.gitlab.com/blog/2016/03/08/gitlab-tutorial-its-all-connected/#mention-others-and-assign) a [maintainer](https://gitlab.com/groups/autowarefoundation/autoware.auto/committers/-/group_members) in the issue for milestone assignment. + 1. The issue template you choose will assign one appropriate label for the issue type (bug, discussion, feature, or improvement). + Assign any additional labels from the available list that you feel are appropriate for the issue's status or other attributes. + +1. Create a fork + + 1. For more information about the fork-and-pull model, see the [Develop in a Fork](@ref develop-in-a-fork) page. + +1. Write code + +1. Create a merge request + + 1. For more information about the fork-and-pull model, see the [Develop in a Fork](@ref develop-in-a-fork) page. + +1. Finish a merge request + + 1. The review process for the MR is as follows: + 1. Submitter adds Reviewer(s) and assigns herself. + 1. Reviewer reviews and submits comments. + 1. Assignee addresses the reviews making necessary changes and notifies Reviewer(s) to have another look. + 1. Repeat 2 and 3 as necessary. + 1. When Reviewer approves, the MR should be assigned to the `@merge-bot` account which will automatically rebase and merge it. + 1. In order for a merge request to be merged to Autoware.Auto, it must meet the following criteria: + - All discussions on the merge request must be resolved. + - All items of the merge-request checklist are checked off. + - CI jobs for the merge request must have passed successfully. + 1. Once your merge request has been accepted by the reviewer, assign the merge request to the `@merge-bot` account. + +## Guidelines for General Code Development + +Only C++14 and below is allowed for functional code. +Python 3.7+ and Bash are allowed for tooling. +CMake is the preferred build system, it should integrate with Colcon. +Deviations need to be approved by the maintainers. + +The requirements for C++14 and Python 3.7+ align with compiler and tooling support found in ROS Foxy. +This may change in the future as new OS or ROS environments are targeted; see @ref target-environments for details. + +### License and Copyright + +Every file should have a license header; see the _License_ section in [CONTRIBUTING.md](https://gitlab.com/autowarefoundation/autoware.auto/AutowareAuto/-/blob/master/CONTRIBUTING.md). + +### Building + +See @ref building. + +### Committing {#contributors-guidelines-committing} + +Developers should commit and push regularly to GitLab to avoid data loss. Commit messages should follow common standards as laid out in this [post](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). In summary, + +1. Write your commit message in the imperative +1. In the mandatory first line, summarize _what_ the functional change is, not _why_ it is introduced +1. Optionally add more details separated by a blank line + +As a general recommendation, add a reference to the issue in the commit message so it is easier for others in the future to get more context about the changes in the commit. If the commit doesn't refer to a particular issue but only touches a particular package or aspect, add a reference to that. + +Example summary line referring to issue #716: + +```{text} +[#716] Expand contributor guidelines +``` + +Example summary line without an issue: + +```{text} +[CI] Disable flaky tests in foo and bar packages +``` + +There is assistance via `git` hooks to help with commit messages. Navigate to `.git/hooks` in the checkout of Autoware.Auto, then: + +```{bash} +ln -s ../../.git-hooks/prepare-commit-msg # prepend issue number +ln -s ../../.git-hooks/commit-msg # check formatting of commit message +``` + +### Cross-platform Compatibility + +It is preferred to use cross-platform solutions for system-level function calls whenever possible. While the C++ standard library should be used for as many tasks as possible, some functions (such as `std::filesystem`) are not available in C++14 in cross-platform implementations. This usually means utilizing libraries like [`asio`](https://think-async.com/Asio/index.html) for networking tasks and [`a std::filesystem shim`](https://github.com/gulrak/filesystem) for filesystem navigation is preferred to creating platform-specific implementations. + +### Documentation + +To check that the code is properly documented and all documents are correctly linked, you can run `AutowareAuto/docs/.doxygen/build.py`. +The generated documentation can be found in `AutowareAuto/docs/_build/html/index.html`. +For more details see the [documentation guide](@ref writing-documentation). + +### Formatting {#contributors-guidelines-formatting} + +Autoware.Auto follows ROS recommendations for code style and formatting. See the [Coding Style and Language Versions entry for C++](https://index.ros.org/doc/ros2/Contributing/Code-Style-Language-Versions/#id3) or the [Coding Style and Language Versions entry for Python](https://index.ros.org/doc/ros2/Contributing/Code-Style-Language-Versions/#python) for more information. We enforce these guidelines using linters provided with `ament` as far as possible. All packages should have the following in their `package.xml` files: + +```{xml} +ament_lint_auto +ament_lint_common +``` + +In addition, the following should be in the package's `CMakeLists.txt` (extended with other tests): + +```{cmake} +if(BUILD_TESTING) + find_package(ament_lint_auto REQUIRED) + ament_lint_auto_find_test_dependencies() +endif() +``` + +In CI, merge requests fail if they introduce improperly formatted code. To avoid that, format the C++ code locally with + +```{bash} +ament_uncrustify --reformat file.cpp # update single file in place +ament_uncrustify --reformat path/to/pkg_foo # update all C++ source files in package +``` + +With the above CMake setup, run all linters together with all other tests of a package as described in the [Running Tests](#contributors-guidelines-run-tests) section or run a specific linter; e.g., + +```{bash} +ament_cpplint path/to/pkg_foo +``` + +Tools such as CLion can parse the output of the previous command and provide fast navigation to offending lines in the code. + +#### Using ament_clang_format + +`ament_uncrustify --reformat` is able to format the code to a degree but its results are generally not enough to pass `ament_cpplint`. To automate the process, `ament_clang_format` can be used like: + +```{bash} +AutowareAuto $ ament_clang_format --config .clang-format --reformat file.cpp +``` + +The configuration is stored in the text file `.clang-format` in the base directory of a source checkout of Autoware.Auto. + +`ament_clang_format` is available in ADE by default. When working outside of ADE, install it e.g. with + +```{bash} +sudo apt install ros-${ROS_DISTRO}-ament-clang-format +``` + +A way to use all these three tools is as follows: + +1. `ament_clang_format --config AutowareAuto/.clang-format --reformat file.cpp` +1. `ament_uncrustify --reformat file.cpp` +1. `ament_cpplint file.cpp` +1. Fix all reported errors +1. Repeat the previous steps until `ament_uncrustify` and `ament_cpplint` give no more errors. + +##### Order of header includes + +The recommended order of `#include` directives is based on the [google styleguide](https://google.github.io/styleguide/cppguide.html#Names_and_Order_of_Includes) + +1. corresponding file: from `bar.cpp` in package `foo`, that's `#include "foo/bar.hpp"` +1. C system headers; e.g. `#include ` +1. C++ system headers; e.g. `#include ` +1. headers from this or other packages; e.g. `#include "pkg/baz.hpp"` +1. message headers; e.g. `#include "foo/msg/bar.hpp"` + +with headers in each group sorted alphabetically and groups separated by a single blank line. + +In order for automatic grouping and sorting to work: + +1. Use `#include "foo/bar.hpp"` for headers from the same and other packages +1. Use `#include ` with **angle brackets only for C and C++ system headers** +1. Invoke `ament_clang_format` like explained above. + +The resulting order should satisfy `ament_cpplint`. + +!!! note + + If cpplint complains about the order of headers, ensure that the delimiters match the above rules. Example error: + + ```console + Found C system header after C++ system header. + ``` + +#### Utilizing git pre-commit + +To lint the code automatically before each commit, activate the `pre-commit` [hook](https://gitlab.com/autowarefoundation/autoware.auto/AutowareAuto/-/blob/master/.git-hooks/pre-commit). From the repository base directory, do: + +```{bash} +cd .git/hooks +ln -s ../../.git-hooks/pre-commit +``` + +### Code Coverage {#contributors-guidelines-coverage} + +For [code coverage](https://en.wikipedia.org/wiki/Code_coverage), we use the popular [GNU tool `lcov`](http://ltp.sourceforge.net/coverage/lcov.php) for generating statistics about line coverage. For every merge request, we run our test suite and report the percentage of lines covered. We aim for a 100% line coverage and continuously improve our test suite to achieve that number. In particular, we do not accept changes that reduce the coverage value. If a merge request has a lower line coverage than `master`, we will request the contributor to add more tests. + +The coverage report for the latest successful CI run on the `master` branch is available [here](https://autowarefoundation.gitlab.io/autoware.auto/AutowareAuto/coverage/index.html). + +Check @ref unit-testing-coverage for details to create that report manually or @ref testing-overview for more information. + +### C++ Resources + +- [cppreference.com](https://en.cppreference.com/w/) +- [C++ Core Guidelines](http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines) + +## Guidelines for ROS Development + +In general, Autoware.Auto follows the [ROS 2 Developer Guide](https://index.ros.org/doc/ros2/Contributing/Developer-Guide/) for contributions, except where noted. Some special items of note that are not described in the ROS 2 Developer Guide are listed below. + +### Creating a New Package + +Basic instructions for creating a new ROS 2 package can be found [in this tutorial](https://index.ros.org//doc/ros2/Tutorials/Colcon-Tutorial/#create-your-own-package). In Autoware.Auto, much of the boilerplate code can be automatically generated by utilizing the `autoware_auto_create_pkg` tool. + +For more information on using the tool, see \ref autoware_auto_create_pkg-package-design. + +### 2-Tier Development Pattern + +In all but the most trivial utilities, it is best to implement a code pattern with _at least_ two tiers of abstraction which would look something like: + +1. A "core," pure C++ class which performs all basic algorithmic and utility functions which are not ROS-related. + + This class may use ROS utilities such as logging or message structures, but such use must be justified in terms of why it cannot be done via the class's external interface (e.g. the enclosing node uses information obtained via the class's external interface to populate log messages). + +1. A "ROS Node" or "ROS Component" class which inherits from `rclcpp::Node` or a subclass, handles all ROS-specific functions. + + This class should instantiate the class defined in 1. and register the node as a [component](#contributors-guidelines-components), so it can be created with launch files. + +In the rare case that fine-grained control over execution is desired, create a main function in a separate file with a [ROS Executor](http://docs.ros2.org/foxy/api/rclcpp/classrclcpp_1_1Executor.html#details) to control provision of execution time of the node in some way (e.g. through calling `spin()`). + +This design pattern helps to promote separation of concerns and code re-use. The core and the ROS node(s) can be implemented in separate packages; e.g. `foo` and `foo_nodes`. There are some trivial cases where a simple ROS Node that does not require a "core" are acceptable but these should be the exception, not the rule. + +### Naming in Autoware.Auto + +The [Naming Guidelines](@ref autoware-common-naming-guidelines) provide for standard, reliable naming and namespacing conventions which should be used in all Autoware.Auto packages. + +### On Topics and Parameters + +In most cases, topics should receive a default name in code and be remapped if needed. Providing topic names as ROS parameters is an anti-pattern, with few exceptions. + +Required parameters should not have default values but fail during construction if no value is provided. + +#### Parameter File Syntax + +To avoid the need to change parameter files based on the namespacing or node name of a node, use the "double-star" syntax. e.g.: + +```{yaml} +/**: + ros__parameters: + param1: value +``` + +The above parameter file can be passed to any node regardless of namespace or name and the parameters will populate those of the node if the declared parameters match those in the file. + +### ROS Components {#contributors-guidelines-components} + +As of ROS Dashing, the recommended way to write Nodes in ROS 2 is using Components. +For more information about components and their use, see [the ROS Composition Guide](https://index.ros.org/doc/ros2/Tutorials/Composition/). +To implement your node as a Component, it must conform to the items below (using `ListenerNode` as an example): + +- Must inherit from `rclcpp::Node` or a subclass (such as `rclcpp::LifecycleNode`) +- Must use a single-argument constructor in the form of: + +```{cpp} +namespace composition_example +{ +class ListenerNode: public rclcpp::Node { + ListenerNode(const rclcpp::NodeOptions & options) + : Node("listener", options) + { + ... + } +} +} // namespace composition_example +``` + +- Must contain a registration macro and header in a single translation unit. For example, the following at the bottom of your `cpp` file would suffice: + +```{cpp} +// Insert at bottom of translation unit, e.g. listener_node.cpp +#include +// Use fully-qualified name in registration +RCLCPP_COMPONENTS_REGISTER_NODE(composition_example::ListenerNode) +``` + +- Must compile the components as a shared library and register them in your `CMakeLists.txt` file. +- Must depend on the `rclcpp_components` package. + +#### Minimal CMake Example {#contributors-guidelines-minimal-cmake-example} + +The following is a minimal `CMakeLists.txt` file which uses the recommended `ament_cmake_auto` macros, registers a single component, builds a stand-alone node which uses the component, and exports it as a dependency for downstream packages. It can be conveniently created by [`autoware_auto_create_pkg`](https://autowarefoundation.gitlab.io/autoware.auto/AutowareAuto/autoware_auto_create_pkg-package-design.html): + +```{cmake} +cmake_minimum_required(VERSION 3.5) +project(composition_example) + +find_package(ament_cmake_auto REQUIRED) +ament_auto_find_build_dependencies() + +ament_auto_add_library(listener_node SHARED src/listener_node.cpp) +autoware_set_compile_options(listener_node) +rclcpp_components_register_nodes(listener_node "composition_example::ListenerNode") + +ament_auto_add_executable(listener_node_exe src/listener_main.cpp) +autoware_set_compile_options(listener_node_exe) + +if(BUILD_TESTING) + find_package(ament_lint_auto REQUIRED) + ament_lint_auto_find_test_dependencies() +endif() + +ament_auto_package() +``` + +##### Compiler settings + +The C++ standard is set in `autoware_auto_cmake.cmake` and becomes available to a package by depending on the `autoware_auto_cmake` package in `package.xml` as shown below. Compiler options and warning flags are set per target by calling the function `autoware_set_compile_options(${target})` defined in `autoware_auto_cmake.cmake` as well. It should be applied to every C++ target and in general Autoware.Auto code shall not generate warnings. + +In case the warning flags are too strict for example when including external code, they can be selectively deactivated in special cases as follows: + +```{cmake} +autoware_set_compile_options(${target}) +target_compile_options(${target} PRIVATE -Wno-double-promotion) +``` + +#### Minimal Package.xml Example {#contributors-guidelines-minimal-package-xml-example} + +The following is a minimal `package.xml` file to go with the above `CMakeLists.txt` example: + +```{xml} + + + + composition_example + 0.0.1 + Example of node composition + The Autoware Foundation + Apache License 2.0 + + ament_cmake_auto + autoware_auto_cmake + + rclcpp + rclcpp_components + + ament_lint_auto + ament_lint_common + + + ament_cmake + + +``` + +### Resources + +- [rclcpp_components in Dashing Diademata Release Notes](https://index.ros.org/doc/ros2/Releases/Release-Dashing-Diademata/#rclcpp-components) diff --git a/docs/contributors_guide/contributors-guidelines.md b/docs/contributors_guide/contributors-guidelines.md deleted file mode 100644 index e1dd7f4c890..00000000000 --- a/docs/contributors_guide/contributors-guidelines.md +++ /dev/null @@ -1,394 +0,0 @@ -Guidelines and Best Practices {#contributor-guidelines} -=========== - -@tableofcontents - -# Contribution Workflow - -1. [Create an issue](https://gitlab.com/autowarefoundation/autoware.auto/AutowareAuto/-/issues/new?issue%5Bassignee_id%5D=&issue%5Bmilestone_id%5D=) defining your intended contribution - 1. Use one of the provided templates [by selecting one from the drop-down list](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates). - 2. Select yourself in the `Assignee` field. - 3. If you have permissions to do so, assign to an appropriate milestone. If you do not have permissions, [mention](https://about.gitlab.com/blog/2016/03/08/gitlab-tutorial-its-all-connected/#mention-others-and-assign) a [maintainer](https://gitlab.com/groups/autowarefoundation/autoware.auto/committers/-/group_members) in the issue for milestone assignment. - 4. The issue template you choose will assign one appropriate label for the issue type (bug, discussion, feature, or improvement). - Assign any additional labels from the available list that you feel are appropriate for the issue's status or other attributes. - -2. Create a fork - 1. For more information about the fork-and-pull model, see the [Develop in a Fork](@ref develop-in-a-fork) page. - -3. Write code - -4. Create a merge request - 1. For more information about the fork-and-pull model, see the [Develop in a Fork](@ref develop-in-a-fork) page. - -5. Finish a merge request - - 1. The review process for the MR is as follows: - 1. Submitter adds Reviewer(s) and assigns herself. - 2. Reviewer reviews and submits comments. - 3. Assignee addresses the reviews making necessary changes and notifies Reviewer(s) to have another look. - 4. Repeat 2 and 3 as necessary. - 5. When Reviewer approves, the MR should be assigned to the `@merge-bot` account which will automatically rebase and merge it. - 2. In order for a merge request to be merged to Autoware.Auto, it must meet the following criteria: - - All discussions on the merge request must be resolved. - - All items of the merge-request checklist are checked off. - - CI jobs for the merge request must have passed successfully. - 3. Once your merge request has been accepted by the reviewer, assign the merge request to the `@merge-bot` account. - - -# Guidelines for General Code Development - -Only C++14 and below is allowed for functional code. -Python 3.7+ and Bash are allowed for tooling. -CMake is the preferred build system, it should integrate with Colcon. -Deviations need to be approved by the maintainers. - -The requirements for C++14 and Python 3.7+ align with compiler and tooling support found in ROS Foxy. -This may change in the future as new OS or ROS environments are targeted; see @ref target-environments for details. - -## License and Copyright -Every file should have a license header; see the *License* section in [CONTRIBUTING.md](https://gitlab.com/autowarefoundation/autoware.auto/AutowareAuto/-/blob/master/CONTRIBUTING.md). - -## Building -See @ref building. - -## Committing {#contributors-guidelines-committing} - -Developers should commit and push regularly to GitLab to avoid data loss. Commit messages should follow -common standards as laid out in this [post](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). In -summary, - -1. Write your commit message in the imperative -1. In the mandatory first line, summarize *what* the functional change is, not *why* it is introduced -1. Optionally add more details separated by a blank line - -As a general recommendation, add a reference to the issue in the commit message so it is easier for others in the future -to get more context about the changes in the commit. If the commit doesn't refer to a particular issue but only touches -a particular package or aspect, add a reference to that. - -Example summary line referring to issue #716: - - [#716] Expand contributor guidelines - -Example summary line without an issue: - - [CI] Disable flaky tests in foo and bar packages - -There is assistance via `git` hooks to help with commit messages. Navigate to `.git/hooks` in the checkout of -Autoware.Auto, then: - -```{bash} -ln -s ../../.git-hooks/prepare-commit-msg # prepend issue number -ln -s ../../.git-hooks/commit-msg # check formatting of commit message -``` -## Cross-platform Compatibility - -It is preferred to use cross-platform solutions for system-level function calls whenever possible. While the C++ -standard library should be used for as many tasks as possible, some functions (such as `std::filesystem`) are not -available in C++14 in cross-platform implementations. This usually means utilizing libraries like -[`asio`](https://think-async.com/Asio/index.html) for networking tasks and [`a std::filesystem -shim`](https://github.com/gulrak/filesystem) for filesystem navigation is preferred to creating platform-specific -implementations. - -## Documentation - -To check that the code is properly documented and all documents are correctly linked, you can run `AutowareAuto/docs/.doxygen/build.py`. -The generated documentation can be found in `AutowareAuto/docs/_build/html/index.html`. -For more details see the [documentation guide](@ref writing-documentation). - -## Formatting {#contributors-guidelines-formatting} - -Autoware.Auto follows ROS recommendations for code style and formatting. See the [Coding Style and Language Versions -entry for C++](https://index.ros.org/doc/ros2/Contributing/Code-Style-Language-Versions/#id3) or the [Coding Style and -Language Versions entry for Python](https://index.ros.org/doc/ros2/Contributing/Code-Style-Language-Versions/#python) -for more information. We enforce these guidelines using linters provided with `ament` as far as possible. All -packages should have the following in their `package.xml` files: - -```{xml} -ament_lint_auto -ament_lint_common -``` - -In addition, the following should be in the package's `CMakeLists.txt` (extended with other tests): - -```{cmake} -if(BUILD_TESTING) - find_package(ament_lint_auto REQUIRED) - ament_lint_auto_find_test_dependencies() -endif() -``` - -In CI, merge requests fail if they introduce improperly formatted code. To avoid that, format the -C++ code locally with - -```{bash} -ament_uncrustify --reformat file.cpp # update single file in place -ament_uncrustify --reformat path/to/pkg_foo # update all C++ source files in package -``` - -With the above CMake setup, run all linters together with all other tests of a package as described in the [Running -Tests](#contributors-guidelines-run-tests) section or run a specific linter; e.g., - -```{bash} -ament_cpplint path/to/pkg_foo -``` - -Tools such as CLion can parse the output of the previous command and provide fast navigation to -offending lines in the code. - -### Using ament_clang_format - -`ament_uncrustify --reformat` is able to format the code to a degree but its results -are generally not enough to pass `ament_cpplint`. To automate the process, -`ament_clang_format` can be used like: -```{bash} -AutowareAuto $ ament_clang_format --config .clang-format --reformat file.cpp -``` - -The configuration is stored in the text file `.clang-format` in the base directory of a source -checkout of Autoware.Auto. - -`ament_clang_format` is available in ADE by default. When working outside of ADE, install it e.g. -with - -```{bash} -sudo apt install ros-${ROS_DISTRO}-ament-clang-format -``` - -A way to use all these three tools is as follows: --# `ament_clang_format --config AutowareAuto/.clang-format --reformat file.cpp` --# `ament_uncrustify --reformat file.cpp` --# `ament_cpplint file.cpp` --# Fix all reported errors --# Repeat the previous steps until `ament_uncrustify` and `ament_cpplint` give no more errors. - -#### Order of header includes - -The recommended order of `#include` directives is based on the [google styleguide](https://google.github.io/styleguide/cppguide.html#Names_and_Order_of_Includes) - --# corresponding file: from `bar.cpp` in package `foo`, that's `#include "foo/bar.hpp"` --# C system headers; e.g. `#include ` --# C++ system headers; e.g. `#include ` --# headers from this or other packages; e.g. `#include "pkg/baz.hpp"` --# message headers; e.g. `#include "foo/msg/bar.hpp"` - -with headers in each group sorted alphabetically and groups separated by a single blank line. - -In order for automatic grouping and sorting to work: - --# Use `#include "foo/bar.hpp"` for headers from the same and other packages --# Use `#include ` with **angle brackets only for C and C++ system headers** --# Invoke `ament_clang_format` like explained above. - -The resulting order should satisfy `ament_cpplint`. - -@note If cpplint complains about the order of headers, ensure that the delimiters match the above -rules. Example error: - -```console -Found C system header after C++ system header. -``` - -### Utilizing git pre-commit - -To lint the code automatically before each commit, activate the `pre-commit` -[hook](https://gitlab.com/autowarefoundation/autoware.auto/AutowareAuto/-/blob/master/.git-hooks/pre-commit). From the -repository base directory, do: - -```{bash} -cd .git/hooks -ln -s ../../.git-hooks/pre-commit -``` - -## Code Coverage {#contributors-guidelines-coverage} - -For [code coverage](https://en.wikipedia.org/wiki/Code_coverage), we use the popular [GNU tool -`lcov`](http://ltp.sourceforge.net/coverage/lcov.php) for generating statistics about line coverage. For every merge -request, we run our test suite and report the percentage of lines covered. We aim for a 100% line coverage and -continuously improve our test suite to achieve that number. In particular, we do not accept changes that reduce the -coverage value. If a merge request has a lower line coverage than `master`, we will request the contributor to add more -tests. - -The coverage report for the latest successful CI run on the `master` branch is available -[here](https://autowarefoundation.gitlab.io/autoware.auto/AutowareAuto/coverage/index.html). - -Check @ref unit-testing-coverage for details to create that report manually or @ref testing-overview for more information. - -## C++ Resources - -- [cppreference.com](https://en.cppreference.com/w/) -- [C++ Core Guidelines](http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines) - -# Guidelines for ROS Development - -In general, Autoware.Auto follows the [ROS 2 Developer -Guide](https://index.ros.org/doc/ros2/Contributing/Developer-Guide/) for contributions, except where noted. Some special -items of note that are not described in the ROS 2 Developer Guide are listed below. - -## Creating a New Package - -Basic instructions for creating a new ROS 2 package can be found [in this -tutorial](https://index.ros.org//doc/ros2/Tutorials/Colcon-Tutorial/#create-your-own-package). In Autoware.Auto, much of -the boilerplate code can be automatically generated by utilizing the `autoware_auto_create_pkg` tool. - -For more information on using the tool, see \ref autoware_auto_create_pkg-package-design. - -## 2-Tier Development Pattern - -In all but the most trivial utilities, it is best to implement a code pattern with *at least* two tiers of abstraction -which would look something like: - -1. A "core," pure C++ class which performs all basic algorithmic and utility functions which are not ROS-related. - - This class may use ROS utilities such as logging or message structures, but such use must be justified in terms of - why it cannot be done via the class's external interface (e.g. the enclosing node uses information obtained via the - class's external interface to populate log messages). -2. A "ROS Node" or "ROS Component" class which inherits from `rclcpp::Node` or a subclass, handles all ROS-specific - functions. - - This class should instantiate the class defined in 1. and register the node as a - [component](#contributors-guidelines-components), so it can be created with launch files. - -In the rare case that fine-grained control over execution is desired, create a main function in a separate file with a -[ROS Executor](http://docs.ros2.org/foxy/api/rclcpp/classrclcpp_1_1Executor.html#details) to control provision of -execution time of the node in some way (e.g. through calling `spin()`). - -This design pattern helps to promote separation of concerns and code re-use. The core and the ROS node(s) can be -implemented in separate packages; e.g. `foo` and `foo_nodes`. There are some trivial cases where a simple ROS Node that -does not require a "core" are acceptable but these should be the exception, not the rule. - -## Naming in Autoware.Auto - -The [Naming Guidelines](@ref autoware-common-naming-guidelines) provide for standard, reliable naming and namespacing -conventions which should be used in all Autoware.Auto packages. - -## On Topics and Parameters - -In most cases, topics should receive a default name in code and be remapped if needed. Providing topic names as ROS -parameters is an anti-pattern, with few exceptions. - -Required parameters should not have default values but fail during construction if no value is provided. - -### Parameter File Syntax - -To avoid the need to change parameter files based on the namespacing or node name of a node, use the "double-star" -syntax. e.g.: - -```{yaml} -/**: - ros__parameters: - param1: value -``` - -The above parameter file can be passed to any node regardless of namespace or name and the parameters will populate -those of the node if the declared parameters match those in the file. - -## ROS Components {#contributors-guidelines-components} - -As of ROS Dashing, the recommended way to write Nodes in ROS 2 is using Components. -For more information about components and their use, see [the ROS Composition Guide](https://index.ros.org/doc/ros2/Tutorials/Composition/). -To implement your node as a Component, it must conform to the items below (using `ListenerNode` as an example): - -- Must inherit from `rclcpp::Node` or a subclass (such as `rclcpp::LifecycleNode`) -- Must use a single-argument constructor in the form of: - -```{cpp} -namespace composition_example -{ -class ListenerNode: public rclcpp::Node { - ListenerNode(const rclcpp::NodeOptions & options) - : Node("listener", options) - { - ... - } -} -} // namespace composition_example -``` - -- Must contain a registration macro and header in a single translation unit. For example, the following at the bottom of your `cpp` file would suffice: - -```{cpp} -// Insert at bottom of translation unit, e.g. listener_node.cpp -#include -// Use fully-qualified name in registration -RCLCPP_COMPONENTS_REGISTER_NODE(composition_example::ListenerNode) -``` - -- Must compile the components as a shared library and register them in your `CMakeLists.txt` file. -- Must depend on the `rclcpp_components` package. - -### Minimal CMake Example {#contributors-guidelines-minimal-cmake-example} - -The following is a minimal `CMakeLists.txt` file which uses the recommended `ament_cmake_auto` macros, registers a -single component, builds a stand-alone node which uses the component, and exports it as a dependency for downstream -packages. It can be conveniently created by -[`autoware_auto_create_pkg`](https://autowarefoundation.gitlab.io/autoware.auto/AutowareAuto/autoware_auto_create_pkg-package-design.html): - -```{cmake} -cmake_minimum_required(VERSION 3.5) -project(composition_example) - -find_package(ament_cmake_auto REQUIRED) -ament_auto_find_build_dependencies() - -ament_auto_add_library(listener_node SHARED src/listener_node.cpp) -autoware_set_compile_options(listener_node) -rclcpp_components_register_nodes(listener_node "composition_example::ListenerNode") - -ament_auto_add_executable(listener_node_exe src/listener_main.cpp) -autoware_set_compile_options(listener_node_exe) - -if(BUILD_TESTING) - find_package(ament_lint_auto REQUIRED) - ament_lint_auto_find_test_dependencies() -endif() - -ament_auto_package() -``` - -#### Compiler settings -The C++ standard is set in `autoware_auto_cmake.cmake` and becomes available to a package by -depending on the `autoware_auto_cmake` package in `package.xml` as shown below. Compiler options and -warning flags are set per target by calling the function `autoware_set_compile_options(${target})` -defined in `autoware_auto_cmake.cmake` as well. It should be applied to every C++ target and in -general Autoware.Auto code shall not generate warnings. - -In case the warning flags are too strict for example when including external code, they can be selectively deactivated in special cases as follows: - -```{cmake} -autoware_set_compile_options(${target}) -target_compile_options(${target} PRIVATE -Wno-double-promotion) -``` - -### Minimal Package.xml Example {#contributors-guidelines-minimal-package-xml-example} - -The following is a minimal `package.xml` file to go with the above `CMakeLists.txt` example: - -```{xml} - - - - composition_example - 0.0.1 - Example of node composition - The Autoware Foundation - Apache License 2.0 - - ament_cmake_auto - autoware_auto_cmake - - rclcpp - rclcpp_components - - ament_lint_auto - ament_lint_common - - - ament_cmake - - -``` - - -## Resources - -- [rclcpp_components in Dashing Diademata Release Notes](https://index.ros.org/doc/ros2/Releases/Release-Dashing-Diademata/#rclcpp-components) From 7292084a1f3401c7f78317e8d9b5744b8fe47fd2 Mon Sep 17 00:00:00 2001 From: Kenji Miyake Date: Fri, 4 Mar 2022 12:36:44 +0900 Subject: [PATCH 03/12] update documents Signed-off-by: Kenji Miyake --- .../contributors-guidelines.md | 351 ------------------ docs/contributing/index.md | 58 ++- 2 files changed, 53 insertions(+), 356 deletions(-) delete mode 100644 docs/contributing/coding-guidelines/contributors-guidelines.md diff --git a/docs/contributing/coding-guidelines/contributors-guidelines.md b/docs/contributing/coding-guidelines/contributors-guidelines.md deleted file mode 100644 index d1b8545d37c..00000000000 --- a/docs/contributing/coding-guidelines/contributors-guidelines.md +++ /dev/null @@ -1,351 +0,0 @@ -# Guidelines and Best Practices - -## Contribution Workflow - -1. [Create an issue](https://gitlab.com/autowarefoundation/autoware.auto/AutowareAuto/-/issues/new?issue%5Bassignee_id%5D=&issue%5Bmilestone_id%5D=) defining your intended contribution - - 1. Use one of the provided templates [by selecting one from the drop-down list](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates). - 1. Select yourself in the `Assignee` field. - 1. If you have permissions to do so, assign to an appropriate milestone. If you do not have permissions, [mention](https://about.gitlab.com/blog/2016/03/08/gitlab-tutorial-its-all-connected/#mention-others-and-assign) a [maintainer](https://gitlab.com/groups/autowarefoundation/autoware.auto/committers/-/group_members) in the issue for milestone assignment. - 1. The issue template you choose will assign one appropriate label for the issue type (bug, discussion, feature, or improvement). - Assign any additional labels from the available list that you feel are appropriate for the issue's status or other attributes. - -1. Create a fork - - 1. For more information about the fork-and-pull model, see the [Develop in a Fork](@ref develop-in-a-fork) page. - -1. Write code - -1. Create a merge request - - 1. For more information about the fork-and-pull model, see the [Develop in a Fork](@ref develop-in-a-fork) page. - -1. Finish a merge request - - 1. The review process for the MR is as follows: - 1. Submitter adds Reviewer(s) and assigns herself. - 1. Reviewer reviews and submits comments. - 1. Assignee addresses the reviews making necessary changes and notifies Reviewer(s) to have another look. - 1. Repeat 2 and 3 as necessary. - 1. When Reviewer approves, the MR should be assigned to the `@merge-bot` account which will automatically rebase and merge it. - 1. In order for a merge request to be merged to Autoware.Auto, it must meet the following criteria: - - All discussions on the merge request must be resolved. - - All items of the merge-request checklist are checked off. - - CI jobs for the merge request must have passed successfully. - 1. Once your merge request has been accepted by the reviewer, assign the merge request to the `@merge-bot` account. - -## Guidelines for General Code Development - -Only C++14 and below is allowed for functional code. -Python 3.7+ and Bash are allowed for tooling. -CMake is the preferred build system, it should integrate with Colcon. -Deviations need to be approved by the maintainers. - -The requirements for C++14 and Python 3.7+ align with compiler and tooling support found in ROS Foxy. -This may change in the future as new OS or ROS environments are targeted; see @ref target-environments for details. - -### License and Copyright - -Every file should have a license header; see the _License_ section in [CONTRIBUTING.md](https://gitlab.com/autowarefoundation/autoware.auto/AutowareAuto/-/blob/master/CONTRIBUTING.md). - -### Building - -See @ref building. - -### Committing {#contributors-guidelines-committing} - -Developers should commit and push regularly to GitLab to avoid data loss. Commit messages should follow common standards as laid out in this [post](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). In summary, - -1. Write your commit message in the imperative -1. In the mandatory first line, summarize _what_ the functional change is, not _why_ it is introduced -1. Optionally add more details separated by a blank line - -As a general recommendation, add a reference to the issue in the commit message so it is easier for others in the future to get more context about the changes in the commit. If the commit doesn't refer to a particular issue but only touches a particular package or aspect, add a reference to that. - -Example summary line referring to issue #716: - -```{text} -[#716] Expand contributor guidelines -``` - -Example summary line without an issue: - -```{text} -[CI] Disable flaky tests in foo and bar packages -``` - -There is assistance via `git` hooks to help with commit messages. Navigate to `.git/hooks` in the checkout of Autoware.Auto, then: - -```{bash} -ln -s ../../.git-hooks/prepare-commit-msg # prepend issue number -ln -s ../../.git-hooks/commit-msg # check formatting of commit message -``` - -### Cross-platform Compatibility - -It is preferred to use cross-platform solutions for system-level function calls whenever possible. While the C++ standard library should be used for as many tasks as possible, some functions (such as `std::filesystem`) are not available in C++14 in cross-platform implementations. This usually means utilizing libraries like [`asio`](https://think-async.com/Asio/index.html) for networking tasks and [`a std::filesystem shim`](https://github.com/gulrak/filesystem) for filesystem navigation is preferred to creating platform-specific implementations. - -### Documentation - -To check that the code is properly documented and all documents are correctly linked, you can run `AutowareAuto/docs/.doxygen/build.py`. -The generated documentation can be found in `AutowareAuto/docs/_build/html/index.html`. -For more details see the [documentation guide](@ref writing-documentation). - -### Formatting {#contributors-guidelines-formatting} - -Autoware.Auto follows ROS recommendations for code style and formatting. See the [Coding Style and Language Versions entry for C++](https://index.ros.org/doc/ros2/Contributing/Code-Style-Language-Versions/#id3) or the [Coding Style and Language Versions entry for Python](https://index.ros.org/doc/ros2/Contributing/Code-Style-Language-Versions/#python) for more information. We enforce these guidelines using linters provided with `ament` as far as possible. All packages should have the following in their `package.xml` files: - -```{xml} -ament_lint_auto -ament_lint_common -``` - -In addition, the following should be in the package's `CMakeLists.txt` (extended with other tests): - -```{cmake} -if(BUILD_TESTING) - find_package(ament_lint_auto REQUIRED) - ament_lint_auto_find_test_dependencies() -endif() -``` - -In CI, merge requests fail if they introduce improperly formatted code. To avoid that, format the C++ code locally with - -```{bash} -ament_uncrustify --reformat file.cpp # update single file in place -ament_uncrustify --reformat path/to/pkg_foo # update all C++ source files in package -``` - -With the above CMake setup, run all linters together with all other tests of a package as described in the [Running Tests](#contributors-guidelines-run-tests) section or run a specific linter; e.g., - -```{bash} -ament_cpplint path/to/pkg_foo -``` - -Tools such as CLion can parse the output of the previous command and provide fast navigation to offending lines in the code. - -#### Using ament_clang_format - -`ament_uncrustify --reformat` is able to format the code to a degree but its results are generally not enough to pass `ament_cpplint`. To automate the process, `ament_clang_format` can be used like: - -```{bash} -AutowareAuto $ ament_clang_format --config .clang-format --reformat file.cpp -``` - -The configuration is stored in the text file `.clang-format` in the base directory of a source checkout of Autoware.Auto. - -`ament_clang_format` is available in ADE by default. When working outside of ADE, install it e.g. with - -```{bash} -sudo apt install ros-${ROS_DISTRO}-ament-clang-format -``` - -A way to use all these three tools is as follows: - -1. `ament_clang_format --config AutowareAuto/.clang-format --reformat file.cpp` -1. `ament_uncrustify --reformat file.cpp` -1. `ament_cpplint file.cpp` -1. Fix all reported errors -1. Repeat the previous steps until `ament_uncrustify` and `ament_cpplint` give no more errors. - -##### Order of header includes - -The recommended order of `#include` directives is based on the [google styleguide](https://google.github.io/styleguide/cppguide.html#Names_and_Order_of_Includes) - -1. corresponding file: from `bar.cpp` in package `foo`, that's `#include "foo/bar.hpp"` -1. C system headers; e.g. `#include ` -1. C++ system headers; e.g. `#include ` -1. headers from this or other packages; e.g. `#include "pkg/baz.hpp"` -1. message headers; e.g. `#include "foo/msg/bar.hpp"` - -with headers in each group sorted alphabetically and groups separated by a single blank line. - -In order for automatic grouping and sorting to work: - -1. Use `#include "foo/bar.hpp"` for headers from the same and other packages -1. Use `#include ` with **angle brackets only for C and C++ system headers** -1. Invoke `ament_clang_format` like explained above. - -The resulting order should satisfy `ament_cpplint`. - -!!! note - - If cpplint complains about the order of headers, ensure that the delimiters match the above rules. Example error: - - ```console - Found C system header after C++ system header. - ``` - -#### Utilizing git pre-commit - -To lint the code automatically before each commit, activate the `pre-commit` [hook](https://gitlab.com/autowarefoundation/autoware.auto/AutowareAuto/-/blob/master/.git-hooks/pre-commit). From the repository base directory, do: - -```{bash} -cd .git/hooks -ln -s ../../.git-hooks/pre-commit -``` - -### Code Coverage {#contributors-guidelines-coverage} - -For [code coverage](https://en.wikipedia.org/wiki/Code_coverage), we use the popular [GNU tool `lcov`](http://ltp.sourceforge.net/coverage/lcov.php) for generating statistics about line coverage. For every merge request, we run our test suite and report the percentage of lines covered. We aim for a 100% line coverage and continuously improve our test suite to achieve that number. In particular, we do not accept changes that reduce the coverage value. If a merge request has a lower line coverage than `master`, we will request the contributor to add more tests. - -The coverage report for the latest successful CI run on the `master` branch is available [here](https://autowarefoundation.gitlab.io/autoware.auto/AutowareAuto/coverage/index.html). - -Check @ref unit-testing-coverage for details to create that report manually or @ref testing-overview for more information. - -### C++ Resources - -- [cppreference.com](https://en.cppreference.com/w/) -- [C++ Core Guidelines](http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines) - -## Guidelines for ROS Development - -In general, Autoware.Auto follows the [ROS 2 Developer Guide](https://index.ros.org/doc/ros2/Contributing/Developer-Guide/) for contributions, except where noted. Some special items of note that are not described in the ROS 2 Developer Guide are listed below. - -### Creating a New Package - -Basic instructions for creating a new ROS 2 package can be found [in this tutorial](https://index.ros.org//doc/ros2/Tutorials/Colcon-Tutorial/#create-your-own-package). In Autoware.Auto, much of the boilerplate code can be automatically generated by utilizing the `autoware_auto_create_pkg` tool. - -For more information on using the tool, see \ref autoware_auto_create_pkg-package-design. - -### 2-Tier Development Pattern - -In all but the most trivial utilities, it is best to implement a code pattern with _at least_ two tiers of abstraction which would look something like: - -1. A "core," pure C++ class which performs all basic algorithmic and utility functions which are not ROS-related. - - This class may use ROS utilities such as logging or message structures, but such use must be justified in terms of why it cannot be done via the class's external interface (e.g. the enclosing node uses information obtained via the class's external interface to populate log messages). - -1. A "ROS Node" or "ROS Component" class which inherits from `rclcpp::Node` or a subclass, handles all ROS-specific functions. - - This class should instantiate the class defined in 1. and register the node as a [component](#contributors-guidelines-components), so it can be created with launch files. - -In the rare case that fine-grained control over execution is desired, create a main function in a separate file with a [ROS Executor](http://docs.ros2.org/foxy/api/rclcpp/classrclcpp_1_1Executor.html#details) to control provision of execution time of the node in some way (e.g. through calling `spin()`). - -This design pattern helps to promote separation of concerns and code re-use. The core and the ROS node(s) can be implemented in separate packages; e.g. `foo` and `foo_nodes`. There are some trivial cases where a simple ROS Node that does not require a "core" are acceptable but these should be the exception, not the rule. - -### Naming in Autoware.Auto - -The [Naming Guidelines](@ref autoware-common-naming-guidelines) provide for standard, reliable naming and namespacing conventions which should be used in all Autoware.Auto packages. - -### On Topics and Parameters - -In most cases, topics should receive a default name in code and be remapped if needed. Providing topic names as ROS parameters is an anti-pattern, with few exceptions. - -Required parameters should not have default values but fail during construction if no value is provided. - -#### Parameter File Syntax - -To avoid the need to change parameter files based on the namespacing or node name of a node, use the "double-star" syntax. e.g.: - -```{yaml} -/**: - ros__parameters: - param1: value -``` - -The above parameter file can be passed to any node regardless of namespace or name and the parameters will populate those of the node if the declared parameters match those in the file. - -### ROS Components {#contributors-guidelines-components} - -As of ROS Dashing, the recommended way to write Nodes in ROS 2 is using Components. -For more information about components and their use, see [the ROS Composition Guide](https://index.ros.org/doc/ros2/Tutorials/Composition/). -To implement your node as a Component, it must conform to the items below (using `ListenerNode` as an example): - -- Must inherit from `rclcpp::Node` or a subclass (such as `rclcpp::LifecycleNode`) -- Must use a single-argument constructor in the form of: - -```{cpp} -namespace composition_example -{ -class ListenerNode: public rclcpp::Node { - ListenerNode(const rclcpp::NodeOptions & options) - : Node("listener", options) - { - ... - } -} -} // namespace composition_example -``` - -- Must contain a registration macro and header in a single translation unit. For example, the following at the bottom of your `cpp` file would suffice: - -```{cpp} -// Insert at bottom of translation unit, e.g. listener_node.cpp -#include -// Use fully-qualified name in registration -RCLCPP_COMPONENTS_REGISTER_NODE(composition_example::ListenerNode) -``` - -- Must compile the components as a shared library and register them in your `CMakeLists.txt` file. -- Must depend on the `rclcpp_components` package. - -#### Minimal CMake Example {#contributors-guidelines-minimal-cmake-example} - -The following is a minimal `CMakeLists.txt` file which uses the recommended `ament_cmake_auto` macros, registers a single component, builds a stand-alone node which uses the component, and exports it as a dependency for downstream packages. It can be conveniently created by [`autoware_auto_create_pkg`](https://autowarefoundation.gitlab.io/autoware.auto/AutowareAuto/autoware_auto_create_pkg-package-design.html): - -```{cmake} -cmake_minimum_required(VERSION 3.5) -project(composition_example) - -find_package(ament_cmake_auto REQUIRED) -ament_auto_find_build_dependencies() - -ament_auto_add_library(listener_node SHARED src/listener_node.cpp) -autoware_set_compile_options(listener_node) -rclcpp_components_register_nodes(listener_node "composition_example::ListenerNode") - -ament_auto_add_executable(listener_node_exe src/listener_main.cpp) -autoware_set_compile_options(listener_node_exe) - -if(BUILD_TESTING) - find_package(ament_lint_auto REQUIRED) - ament_lint_auto_find_test_dependencies() -endif() - -ament_auto_package() -``` - -##### Compiler settings - -The C++ standard is set in `autoware_auto_cmake.cmake` and becomes available to a package by depending on the `autoware_auto_cmake` package in `package.xml` as shown below. Compiler options and warning flags are set per target by calling the function `autoware_set_compile_options(${target})` defined in `autoware_auto_cmake.cmake` as well. It should be applied to every C++ target and in general Autoware.Auto code shall not generate warnings. - -In case the warning flags are too strict for example when including external code, they can be selectively deactivated in special cases as follows: - -```{cmake} -autoware_set_compile_options(${target}) -target_compile_options(${target} PRIVATE -Wno-double-promotion) -``` - -#### Minimal Package.xml Example {#contributors-guidelines-minimal-package-xml-example} - -The following is a minimal `package.xml` file to go with the above `CMakeLists.txt` example: - -```{xml} - - - - composition_example - 0.0.1 - Example of node composition - The Autoware Foundation - Apache License 2.0 - - ament_cmake_auto - autoware_auto_cmake - - rclcpp - rclcpp_components - - ament_lint_auto - ament_lint_common - - - ament_cmake - - -``` - -### Resources - -- [rclcpp_components in Dashing Diademata Release Notes](https://index.ros.org/doc/ros2/Releases/Release-Dashing-Diademata/#rclcpp-components) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 3f8398267e8..3f38bf9e584 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -1,15 +1,63 @@ # Contributing -!!! warning +This page explains how to contribute to Autoware. - Under Construction +First, confirm the [Code of conduct](#contribution-workflows) section for the general manners in contributions. + +See the [Contribution workflows](#contribution-workflows) section for the workflows. +Also, confirm the following our guidelines depending on your situation: + +- [Coding guidelines](coding-guidelines/index.md): when you write source code +- [Testing guidelines](testing-guidelines/index.md): when you write tests +- [Documentation guidelines](documentation-guidelines/index.md): when you write documents +- [Pull request guidelines](pull-request-guidelines/index.md): when you submit pull requests +- [Discussion guidelines](discussion-guidelines/index.md): when you discuss with other contributors +- [Support guidelines](../help/support-guidelines.md): when you need any help + +It is recommended to read the [Contributing pages in ROS 2 Docs](https://docs.ros.org/en/rolling/Contributing.html) as well because Autoware's guidelines generally depend on them. + +For general information about OSS contributions, [Open Source Guides](https://opensource.guide/) by GitHub is a good resource. + +## Code of conduct + +We welcome contributions from everyone. +To ensure our community stays open and healthy, we adhere to the [Contributor Covenant](https://www.contributor-covenant.org/), a widely used [code of conduct](https://github.com/autowarefoundation/autoware/blob/main/CODE_OF_CONDUCT.md) adopted by many other communities listed [here](https://www.contributor-covenant.org/adopters/). + +Everyone participating in the Autoware community is expected to follow the code of conduct. +If someone in the community happens to be violating these terms, let the maintainers know, and we will address it as soon as possible. + +!!!warning + + Note that contributions that ignore guidelines are not contributions but nuisances. ## Contribution workflows -### Issues +There are several types of contributions and the workflows differ between the types. +See the description for your contribution type. ### Discussions -### Small pull requests +You can contribute to Autoware by facilitating discussions: + +- Find a bug and open a new issue. +- Propose an idea of features that will enhance Autoware. +- Join an existing discussion and express your opinion. +- Organize discussion so far for others contributors. +- Answer an question and support other contributors. + +See our [support guidelines](../help/support-guidelines.md) for the detailed steps. + +### Pull requests + +You can directly submit a pull request if it is small like the following: + +- Update a small part of documents. +- Fix spelling mistakes. +- Fix CI failures. +- Fix warnings detected by compilers or analysis tools. + +Otherwise, create an issue or a discussion thread before submitting a pull request and discuss the approach with maintainers. + +Also, regardless of the size of your pull request, follow the pull request template of the target repository. -### Large pull requests +See our [pull request guidelines](pull-request-guidelines/index.md) for the detailed steps. From c5e7491da9d3cf7dd3d4721c16b63b3987eebf4e Mon Sep 17 00:00:00 2001 From: Kenji Miyake Date: Sat, 5 Mar 2022 22:11:00 +0900 Subject: [PATCH 04/12] update Signed-off-by: Kenji Miyake --- docs/contributing/index.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 3f38bf9e584..977d9c6b7ca 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -18,6 +18,10 @@ It is recommended to read the [Contributing pages in ROS 2 Docs](https://docs.ro For general information about OSS contributions, [Open Source Guides](https://opensource.guide/) by GitHub is a good resource. +!!!info + + If you want to apply a new or different rule, you can open a new discussion thread and propose it. + ## Code of conduct We welcome contributions from everyone. From eb186edb9bead08a52d88a381610ad9fabaeec6c Mon Sep 17 00:00:00 2001 From: Kenji Miyake <31987104+kenji-miyake@users.noreply.github.com> Date: Wed, 9 Mar 2022 17:22:56 +0900 Subject: [PATCH 05/12] Update docs/contributing/index.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: M. Fatih Cırıt --- docs/contributing/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 977d9c6b7ca..61c5c7fbf7c 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -2,7 +2,7 @@ This page explains how to contribute to Autoware. -First, confirm the [Code of conduct](#contribution-workflows) section for the general manners in contributions. +First, conform to the [Code of conduct](#contribution-workflows) section for the general manners in contributions. See the [Contribution workflows](#contribution-workflows) section for the workflows. Also, confirm the following our guidelines depending on your situation: From 81e7b67fa6decc117052c6f243f262f8584ad786 Mon Sep 17 00:00:00 2001 From: Kenji Miyake <31987104+kenji-miyake@users.noreply.github.com> Date: Wed, 9 Mar 2022 17:23:26 +0900 Subject: [PATCH 06/12] Update docs/contributing/index.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: M. Fatih Cırıt --- docs/contributing/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 61c5c7fbf7c..d078563c8aa 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -5,7 +5,7 @@ This page explains how to contribute to Autoware. First, conform to the [Code of conduct](#contribution-workflows) section for the general manners in contributions. See the [Contribution workflows](#contribution-workflows) section for the workflows. -Also, confirm the following our guidelines depending on your situation: +Also, make sure the contribution is in line with the following guidelines: - [Coding guidelines](coding-guidelines/index.md): when you write source code - [Testing guidelines](testing-guidelines/index.md): when you write tests From 99ff284ab450157df817c2876aba5313bb5b68a3 Mon Sep 17 00:00:00 2001 From: Kenji Miyake <31987104+kenji-miyake@users.noreply.github.com> Date: Wed, 9 Mar 2022 17:24:00 +0900 Subject: [PATCH 07/12] Update docs/contributing/index.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: M. Fatih Cırıt --- docs/contributing/index.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index d078563c8aa..d30b8cc7c16 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -7,12 +7,12 @@ First, conform to the [Code of conduct](#contribution-workflows) section for the See the [Contribution workflows](#contribution-workflows) section for the workflows. Also, make sure the contribution is in line with the following guidelines: -- [Coding guidelines](coding-guidelines/index.md): when you write source code -- [Testing guidelines](testing-guidelines/index.md): when you write tests -- [Documentation guidelines](documentation-guidelines/index.md): when you write documents -- [Pull request guidelines](pull-request-guidelines/index.md): when you submit pull requests -- [Discussion guidelines](discussion-guidelines/index.md): when you discuss with other contributors -- [Support guidelines](../help/support-guidelines.md): when you need any help +- [Coding guidelines](coding-guidelines/index.md): for contributing source code +- [Testing guidelines](testing-guidelines/index.md): for contributing tests +- [Documentation guidelines](documentation-guidelines/index.md): for contributing documents +- [Pull request guidelines](pull-request-guidelines/index.md): for submitting pull requests +- [Discussion guidelines](discussion-guidelines/index.md): for discussing with other contributors +- [Support guidelines](../help/support-guidelines.md): for finding the right channel when you need help It is recommended to read the [Contributing pages in ROS 2 Docs](https://docs.ros.org/en/rolling/Contributing.html) as well because Autoware's guidelines generally depend on them. From 666deb7dfa4892e70958aa2ef68e1c023ced5275 Mon Sep 17 00:00:00 2001 From: Kenji Miyake <31987104+kenji-miyake@users.noreply.github.com> Date: Wed, 9 Mar 2022 17:27:41 +0900 Subject: [PATCH 08/12] Update docs/contributing/index.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: M. Fatih Cırıt --- docs/contributing/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index d30b8cc7c16..35ca26166e8 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -47,7 +47,7 @@ You can contribute to Autoware by facilitating discussions: - Propose an idea of features that will enhance Autoware. - Join an existing discussion and express your opinion. - Organize discussion so far for others contributors. -- Answer an question and support other contributors. +- Answer questions and support other contributors. See our [support guidelines](../help/support-guidelines.md) for the detailed steps. From 5181600c390fe6515ec6c73f1cda79dae72c075c Mon Sep 17 00:00:00 2001 From: Kenji Miyake <31987104+kenji-miyake@users.noreply.github.com> Date: Wed, 9 Mar 2022 17:39:11 +0900 Subject: [PATCH 09/12] Update docs/contributing/index.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: M. Fatih Cırıt --- docs/contributing/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 35ca26166e8..a0c8d8d79af 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -59,6 +59,7 @@ You can directly submit a pull request if it is small like the following: - Fix spelling mistakes. - Fix CI failures. - Fix warnings detected by compilers or analysis tools. +- Make small changes to a single package. Otherwise, create an issue or a discussion thread before submitting a pull request and discuss the approach with maintainers. From 7dcdcb8aff10f058a240b6c8ff638a2a81f6b2f7 Mon Sep 17 00:00:00 2001 From: Kenji Miyake <31987104+kenji-miyake@users.noreply.github.com> Date: Wed, 9 Mar 2022 17:40:39 +0900 Subject: [PATCH 10/12] Update docs/contributing/index.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: M. Fatih Cırıt --- docs/contributing/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index a0c8d8d79af..9be3b397965 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -46,7 +46,7 @@ You can contribute to Autoware by facilitating discussions: - Find a bug and open a new issue. - Propose an idea of features that will enhance Autoware. - Join an existing discussion and express your opinion. -- Organize discussion so far for others contributors. +- Organize discussions for other contributors. - Answer questions and support other contributors. See our [support guidelines](../help/support-guidelines.md) for the detailed steps. From 56d3c01191264f0ff3eafe0ad3f72fc0fa8b1f2b Mon Sep 17 00:00:00 2001 From: Kenji Miyake <31987104+kenji-miyake@users.noreply.github.com> Date: Wed, 9 Mar 2022 17:50:28 +0900 Subject: [PATCH 11/12] Update docs/contributing/index.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: M. Fatih Cırıt --- docs/contributing/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 9be3b397965..2bc30daaa23 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -53,7 +53,7 @@ See our [support guidelines](../help/support-guidelines.md) for the detailed ste ### Pull requests -You can directly submit a pull request if it is small like the following: +You can submit a pull request directly (without opening an issue) if it is small like the following: - Update a small part of documents. - Fix spelling mistakes. From 1a53b508c96b0f4ae9dd664319f1f8e0c2693223 Mon Sep 17 00:00:00 2001 From: Kenji Miyake <31987104+kenji-miyake@users.noreply.github.com> Date: Wed, 9 Mar 2022 18:11:57 +0900 Subject: [PATCH 12/12] Update docs/contributing/index.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: M. Fatih Cırıt --- docs/contributing/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 2bc30daaa23..ccf50522da7 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -20,7 +20,7 @@ For general information about OSS contributions, [Open Source Guides](https://op !!!info - If you want to apply a new or different rule, you can open a new discussion thread and propose it. + If you want to make changes to the guidelines in this documentation site, you can open a new discussion thread and propose it. ## Code of conduct