From c532ae3792c4ebca316faa5f5d57f5b7c1379290 Mon Sep 17 00:00:00 2001 From: Tully Foote Date: Mon, 4 Nov 2024 20:21:52 +0000 Subject: [PATCH 1/9] add cross reference for quality guide --- source/The-ROS2-Project/Contributing/Developer-Guide.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/source/The-ROS2-Project/Contributing/Developer-Guide.rst b/source/The-ROS2-Project/Contributing/Developer-Guide.rst index a066da777d..eeda7145a2 100644 --- a/source/The-ROS2-Project/Contributing/Developer-Guide.rst +++ b/source/The-ROS2-Project/Contributing/Developer-Guide.rst @@ -36,6 +36,8 @@ The categories are differentiated by their policies on versioning, testing, docu The following sections are the specific development rules we follow to ensure core packages are of the highest quality ('Level 1'). We recommend all ROS developers strive to adhere to the following policies to ensure quality across the ROS ecosystem. +For more specific code recommendations please see :doc:`the Quality Guide ` + .. _semver: Versioning @@ -57,7 +59,7 @@ We will also adhere to some ROS-specific rules built on top of ``semver's`` full * For compiled code, the ABI is considered part of the public interface. Any change that requires recompiling dependent code is considered major (breaking). - * ABI breaking changes *can* be made in a minor version bump *before* a distribution release (getting added to the rolling release). + * ABI breaking changegit@github.com:ros2/ros2_documentation.gits *can* be made in a minor version bump *before* a distribution release (getting added to the rolling release). * We enforce API stability for core packages in Dashing and Eloquent even though their major version components are ``0``, despite `SemVer's specification `_ regarding initial development. From 0067b1e3da914ffa807dce74cc3bb57bfc1dc0d1 Mon Sep 17 00:00:00 2001 From: Tully Foote Date: Mon, 4 Nov 2024 20:38:55 +0000 Subject: [PATCH 2/9] import package naming conventions This is a port of the material at https://wiki.ros.org/ROS/Patterns/Conventions --- .../Contributing/Developer-Guide.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/source/The-ROS2-Project/Contributing/Developer-Guide.rst b/source/The-ROS2-Project/Contributing/Developer-Guide.rst index eeda7145a2..2c6bc676f7 100644 --- a/source/The-ROS2-Project/Contributing/Developer-Guide.rst +++ b/source/The-ROS2-Project/Contributing/Developer-Guide.rst @@ -420,6 +420,22 @@ Depending on the complexity, it might be useful to describe how you plan to addr We will update the status (if you don't have the permission) and you can start working on a pull request. If you contribute regularly we will likely just grant you permission to manage the labels etc. yourself. +Package Naming Conventions +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Names play an important role in ROS and following naming conventions simplifies the process of learning and understanding large systems. + +The ROS packages occupy a flat namespace, so naming should be done carefully and consistently. There is a standard for package naming in `REP-144 `__ + +* Package names should follow common C variable naming conventions: lower case, start with a letter, use underscore separators, e.g. laser_viewer +* Package names should be specific enough to identify what the package does. For example, a motion planner is not called planner. If it implements the wavefront propagation algorithm, it might be called wavefront_planner. There's obviously tension between making a name specific and keeping it from becoming overly verbose. + * Using catchall names such as utils should be avoided as they do not scope what goes into the package or what should be outside the package. +* To check whether a name is taken, consult ``_. If you'd like your repository included in that list, see the `rosdistro Contributing Guide `__. +* Our goal is to develop a canonical set of tools for making robots do interesting things. The package name should tell you what the package does, not where it came from. It should be possible for us, as a community, to make this work. An Ubuntu distribution offers approximately 33,000 packages without inserting origin or authorship into names. +* Prefixing a package name is recommended only when the package is not meant to be used more widely (e.g., packages that are specific to the PR2 robot use the \'pr2_\' prefix). You might prefix the package name when forking an existing package, but again, the prefix would hopefully communicate what changed, not who changed it. +* Prefixing a package name with 'ros' is redundant for a ROS package. This is not recommended except for very core packages. + + Programming conventions ^^^^^^^^^^^^^^^^^^^^^^^ From 3d952c1225999c83622ad42ed0127913d57a99ed Mon Sep 17 00:00:00 2001 From: Tully Foote Date: Mon, 4 Nov 2024 14:04:54 -0800 Subject: [PATCH 3/9] Remove accidental paste Signed-off-by: Tully Foote --- source/The-ROS2-Project/Contributing/Developer-Guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/The-ROS2-Project/Contributing/Developer-Guide.rst b/source/The-ROS2-Project/Contributing/Developer-Guide.rst index 2c6bc676f7..f4c2b4ff7e 100644 --- a/source/The-ROS2-Project/Contributing/Developer-Guide.rst +++ b/source/The-ROS2-Project/Contributing/Developer-Guide.rst @@ -59,7 +59,7 @@ We will also adhere to some ROS-specific rules built on top of ``semver's`` full * For compiled code, the ABI is considered part of the public interface. Any change that requires recompiling dependent code is considered major (breaking). - * ABI breaking changegit@github.com:ros2/ros2_documentation.gits *can* be made in a minor version bump *before* a distribution release (getting added to the rolling release). + * ABI breaking changes *can* be made in a minor version bump *before* a distribution release (getting added to the rolling release). * We enforce API stability for core packages in Dashing and Eloquent even though their major version components are ``0``, despite `SemVer's specification `_ regarding initial development. From 6da4e65c64b91221362e50052d9a34cf9b8911be Mon Sep 17 00:00:00 2001 From: Tully Foote Date: Mon, 4 Nov 2024 14:32:46 -0800 Subject: [PATCH 4/9] Add unit convetions too --- source/The-ROS2-Project/Contributing/Developer-Guide.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/source/The-ROS2-Project/Contributing/Developer-Guide.rst b/source/The-ROS2-Project/Contributing/Developer-Guide.rst index f4c2b4ff7e..de89bb82b0 100644 --- a/source/The-ROS2-Project/Contributing/Developer-Guide.rst +++ b/source/The-ROS2-Project/Contributing/Developer-Guide.rst @@ -435,6 +435,13 @@ The ROS packages occupy a flat namespace, so naming should be done carefully and * Prefixing a package name is recommended only when the package is not meant to be used more widely (e.g., packages that are specific to the PR2 robot use the \'pr2_\' prefix). You might prefix the package name when forking an existing package, but again, the prefix would hopefully communicate what changed, not who changed it. * Prefixing a package name with 'ros' is redundant for a ROS package. This is not recommended except for very core packages. +Units of Measure and Coordinate System Conventions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Standard units and coordinate conventions for use in ROS have been formalized in `REP-103 `__. +All messages should follow these guidelines unless there's a very strong reason which is very clearly documented to avoid confusion. + +Representation of special conditions within distance measurements like "too close" or "too far" in ROS have been formalized in `REP-0117 `__. Programming conventions ^^^^^^^^^^^^^^^^^^^^^^^ From d019184fd36b8272f4c1e03deaebf2bd67c25b9e Mon Sep 17 00:00:00 2001 From: Tully Foote Date: Mon, 4 Nov 2024 14:39:02 -0800 Subject: [PATCH 5/9] fix quotes --- source/The-ROS2-Project/Contributing/Developer-Guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/The-ROS2-Project/Contributing/Developer-Guide.rst b/source/The-ROS2-Project/Contributing/Developer-Guide.rst index de89bb82b0..6595a9bda4 100644 --- a/source/The-ROS2-Project/Contributing/Developer-Guide.rst +++ b/source/The-ROS2-Project/Contributing/Developer-Guide.rst @@ -432,7 +432,7 @@ The ROS packages occupy a flat namespace, so naming should be done carefully and * Using catchall names such as utils should be avoided as they do not scope what goes into the package or what should be outside the package. * To check whether a name is taken, consult ``_. If you'd like your repository included in that list, see the `rosdistro Contributing Guide `__. * Our goal is to develop a canonical set of tools for making robots do interesting things. The package name should tell you what the package does, not where it came from. It should be possible for us, as a community, to make this work. An Ubuntu distribution offers approximately 33,000 packages without inserting origin or authorship into names. -* Prefixing a package name is recommended only when the package is not meant to be used more widely (e.g., packages that are specific to the PR2 robot use the \'pr2_\' prefix). You might prefix the package name when forking an existing package, but again, the prefix would hopefully communicate what changed, not who changed it. +* Prefixing a package name is recommended only when the package is not meant to be used more widely (e.g., packages that are specific to the PR2 robot use the ``pr2_`` prefix). You might prefix the package name when forking an existing package, but again, the prefix would hopefully communicate what changed, not who changed it. * Prefixing a package name with 'ros' is redundant for a ROS package. This is not recommended except for very core packages. Units of Measure and Coordinate System Conventions From 4b99c8a4d633eeeaf5f72c16a55465b55d63ed0d Mon Sep 17 00:00:00 2001 From: Tully Foote Date: Fri, 8 Nov 2024 11:46:17 -0800 Subject: [PATCH 6/9] Fix link syntax Co-authored-by: Christophe Bedard Signed-off-by: Tully Foote --- source/The-ROS2-Project/Contributing/Developer-Guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/The-ROS2-Project/Contributing/Developer-Guide.rst b/source/The-ROS2-Project/Contributing/Developer-Guide.rst index 6595a9bda4..aa7ff33ffd 100644 --- a/source/The-ROS2-Project/Contributing/Developer-Guide.rst +++ b/source/The-ROS2-Project/Contributing/Developer-Guide.rst @@ -430,7 +430,7 @@ The ROS packages occupy a flat namespace, so naming should be done carefully and * Package names should follow common C variable naming conventions: lower case, start with a letter, use underscore separators, e.g. laser_viewer * Package names should be specific enough to identify what the package does. For example, a motion planner is not called planner. If it implements the wavefront propagation algorithm, it might be called wavefront_planner. There's obviously tension between making a name specific and keeping it from becoming overly verbose. * Using catchall names such as utils should be avoided as they do not scope what goes into the package or what should be outside the package. -* To check whether a name is taken, consult ``_. If you'd like your repository included in that list, see the `rosdistro Contributing Guide `__. +* To check whether a name is taken, consult ``__. If you'd like your repository included in that list, see the `rosdistro Contributing Guide `__. * Our goal is to develop a canonical set of tools for making robots do interesting things. The package name should tell you what the package does, not where it came from. It should be possible for us, as a community, to make this work. An Ubuntu distribution offers approximately 33,000 packages without inserting origin or authorship into names. * Prefixing a package name is recommended only when the package is not meant to be used more widely (e.g., packages that are specific to the PR2 robot use the ``pr2_`` prefix). You might prefix the package name when forking an existing package, but again, the prefix would hopefully communicate what changed, not who changed it. * Prefixing a package name with 'ros' is redundant for a ROS package. This is not recommended except for very core packages. From d7ee52553d66356f3b1d90368689460d85d4f96b Mon Sep 17 00:00:00 2001 From: Tully Foote Date: Fri, 8 Nov 2024 11:46:54 -0800 Subject: [PATCH 7/9] Add period Co-authored-by: Christophe Bedard Signed-off-by: Tully Foote --- source/The-ROS2-Project/Contributing/Developer-Guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/The-ROS2-Project/Contributing/Developer-Guide.rst b/source/The-ROS2-Project/Contributing/Developer-Guide.rst index aa7ff33ffd..21331246f1 100644 --- a/source/The-ROS2-Project/Contributing/Developer-Guide.rst +++ b/source/The-ROS2-Project/Contributing/Developer-Guide.rst @@ -36,7 +36,7 @@ The categories are differentiated by their policies on versioning, testing, docu The following sections are the specific development rules we follow to ensure core packages are of the highest quality ('Level 1'). We recommend all ROS developers strive to adhere to the following policies to ensure quality across the ROS ecosystem. -For more specific code recommendations please see :doc:`the Quality Guide ` +For more specific code recommendations please see :doc:`the Quality Guide `. .. _semver: From 031da8d8e81c2118dc552fd485d4efb0f14e8daf Mon Sep 17 00:00:00 2001 From: Tully Foote Date: Fri, 8 Nov 2024 11:51:47 -0800 Subject: [PATCH 8/9] FIx sentence wraps --- .../Contributing/Developer-Guide.rst | 25 +++++++++++++++---- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/source/The-ROS2-Project/Contributing/Developer-Guide.rst b/source/The-ROS2-Project/Contributing/Developer-Guide.rst index 21331246f1..00c1440934 100644 --- a/source/The-ROS2-Project/Contributing/Developer-Guide.rst +++ b/source/The-ROS2-Project/Contributing/Developer-Guide.rst @@ -428,12 +428,27 @@ Names play an important role in ROS and following naming conventions simplifies The ROS packages occupy a flat namespace, so naming should be done carefully and consistently. There is a standard for package naming in `REP-144 `__ * Package names should follow common C variable naming conventions: lower case, start with a letter, use underscore separators, e.g. laser_viewer -* Package names should be specific enough to identify what the package does. For example, a motion planner is not called planner. If it implements the wavefront propagation algorithm, it might be called wavefront_planner. There's obviously tension between making a name specific and keeping it from becoming overly verbose. + +* Package names should be specific enough to identify what the package does. + For example, a motion planner is not called planner. + If it implements the wavefront propagation algorithm, it might be called wavefront_planner. + There's obviously tension between making a name specific and keeping it from becoming overly verbose. + * Using catchall names such as utils should be avoided as they do not scope what goes into the package or what should be outside the package. -* To check whether a name is taken, consult ``__. If you'd like your repository included in that list, see the `rosdistro Contributing Guide `__. -* Our goal is to develop a canonical set of tools for making robots do interesting things. The package name should tell you what the package does, not where it came from. It should be possible for us, as a community, to make this work. An Ubuntu distribution offers approximately 33,000 packages without inserting origin or authorship into names. -* Prefixing a package name is recommended only when the package is not meant to be used more widely (e.g., packages that are specific to the PR2 robot use the ``pr2_`` prefix). You might prefix the package name when forking an existing package, but again, the prefix would hopefully communicate what changed, not who changed it. -* Prefixing a package name with 'ros' is redundant for a ROS package. This is not recommended except for very core packages. + +* To check whether a name is taken, consult ``__. + If you'd like your repository included in that list, see the `rosdistro Contributing Guide `__. + +* Our goal is to develop a canonical set of tools for making robots do interesting things. + The package name should tell you what the package does, not where it came from. + It should be possible for us, as a community, to make this work. + An Ubuntu distribution offers approximately 33,000 packages without inserting origin or authorship into names. + +* Prefixing a package name is recommended only when the package is not meant to be used more widely (e.g., packages that are specific to the PR2 robot use the ``pr2_`` prefix). + You might prefix the package name when forking an existing package, but again, the prefix would hopefully communicate what changed, not who changed it. + +* Prefixing a package name with 'ros' is redundant for a ROS package. + This is not recommended except for very core packages. Units of Measure and Coordinate System Conventions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From 76e58460684135015ce293bed307b6b36c85746e Mon Sep 17 00:00:00 2001 From: Tully Foote Date: Mon, 11 Nov 2024 13:00:57 -0800 Subject: [PATCH 9/9] Update source/The-ROS2-Project/Contributing/Developer-Guide.rst Co-authored-by: Christophe Bedard Signed-off-by: Tully Foote --- source/The-ROS2-Project/Contributing/Developer-Guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/The-ROS2-Project/Contributing/Developer-Guide.rst b/source/The-ROS2-Project/Contributing/Developer-Guide.rst index 00c1440934..e0fb2b40b6 100644 --- a/source/The-ROS2-Project/Contributing/Developer-Guide.rst +++ b/source/The-ROS2-Project/Contributing/Developer-Guide.rst @@ -436,7 +436,7 @@ The ROS packages occupy a flat namespace, so naming should be done carefully and * Using catchall names such as utils should be avoided as they do not scope what goes into the package or what should be outside the package. -* To check whether a name is taken, consult ``__. +* To check whether a name is taken, consult ``__. If you'd like your repository included in that list, see the `rosdistro Contributing Guide `__. * Our goal is to develop a canonical set of tools for making robots do interesting things.