Include much more information in the intro block #28
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Co-authored-by: kscottz <[email protected]>
clalancette
requested changes
Oct 11, 2024
|
|
||
| This is an automated review generated by the [rosdistro-reviewer tool](https://github.com/ros-infrastructure/rosdistro-reviewer). If you'd like the tool to run again, just [re-request review from GitHub Actions](https://github.com/ros-infrastructure/rosdistro-reviewer?tab=readme-ov-file#running-rosdistro-reviewer-in-github-actions). | ||
| This is an automated tool that helps check your pull request for correctness. This tool checks a number of attributes associated with your ROS package and generates a report that helps our reviewers merge your pull request in a timely fashion. Here are a few things to consider when sending adding or updating a package to ROS Distro. ROS Distro includes a very helpful [CONTRIBUTING.md](https://github.com/ros/rosdistro/blob/master/CONTRIBUTING.md) file that we recommend reading if it is your first time submitting a package. Please also read the [ROS Distro review guidelines](https://github.com/rosdistro/rosdistro/blob/master/REVIEW_GUIDELINES.md) which summarizes this release process. |
There was a problem hiding this comment.
I'm going to suggest one sentence per-line here, just for ease of future maintenance (this supposes that the block will render the same regardless of whether there is a newline between sentences or not).
| This is an automated review generated by the [rosdistro-reviewer tool](https://github.com/ros-infrastructure/rosdistro-reviewer). If you'd like the tool to run again, just [re-request review from GitHub Actions](https://github.com/ros-infrastructure/rosdistro-reviewer?tab=readme-ov-file#running-rosdistro-reviewer-in-github-actions). | ||
| This is an automated tool that helps check your pull request for correctness. This tool checks a number of attributes associated with your ROS package and generates a report that helps our reviewers merge your pull request in a timely fashion. Here are a few things to consider when sending adding or updating a package to ROS Distro. ROS Distro includes a very helpful [CONTRIBUTING.md](https://github.com/ros/rosdistro/blob/master/CONTRIBUTING.md) file that we recommend reading if it is your first time submitting a package. Please also read the [ROS Distro review guidelines](https://github.com/rosdistro/rosdistro/blob/master/REVIEW_GUIDELINES.md) which summarizes this release process. | ||
|
|
||
| If you'd like to run this tool again to generate a new review for your PR, just [re-request review from GitHub Actions](https://github.com/ros-infrastructure/rosdistro-reviewer?tab=readme-ov-file#running-rosdistro-reviewer-in-github-actions). |
There was a problem hiding this comment.
To channel @sloretz ; let's get rid of the "just":
Suggested change
| If you'd like to run this tool again to generate a new review for your PR, just [re-request review from GitHub Actions](https://github.com/ros-infrastructure/rosdistro-reviewer?tab=readme-ov-file#running-rosdistro-reviewer-in-github-actions). | |
| If you'd like to run this tool again to generate a new review for your PR, [re-request review from GitHub Actions](https://github.com/ros-infrastructure/rosdistro-reviewer?tab=readme-ov-file#running-rosdistro-reviewer-in-github-actions). |
| # ROS Distro Considerations | ||
| * ROS Distribtutions are created using [REP-134 Standards Track](https://ros.org/reps/rep-0143.html) as a guide. | ||
| * Your package name should comply to [REP-144 ROS Package Naming](https://www.ros.org/reps/rep-0144.html) | ||
| * Your pacakge must build for all platforms and architectures on the ROS buildfarm. See [REP-2000 ROS Releases and Supported Platforms](https://www.ros.org/reps/rep-2000.html) for all supported platforms for your ROS Distro. |
There was a problem hiding this comment.
Suggested change
| * Your pacakge must build for all platforms and architectures on the ROS buildfarm. See [REP-2000 ROS Releases and Supported Platforms](https://www.ros.org/reps/rep-2000.html) for all supported platforms for your ROS Distro. | |
| * Your package must build for all platforms and architectures on the ROS buildfarm. See [REP-2000 ROS Releases and Supported Platforms](https://www.ros.org/reps/rep-2000.html) for all supported platforms for your ROS Distro. |
There was a problem hiding this comment.
Actually, this isn't entirely true. We allow packages that build for Ubuntu but not RHEL. But also the spelling error :P
| * Your package name should comply to [REP-144 ROS Package Naming](https://www.ros.org/reps/rep-0144.html) | ||
| * Your pacakge must build for all platforms and architectures on the ROS buildfarm. See [REP-2000 ROS Releases and Supported Platforms](https://www.ros.org/reps/rep-2000.html) for all supported platforms for your ROS Distro. | ||
| * Your package must contain an [OSI approved license](https://opensource.org/licenses). Your `package.xml` file must also include that license in a machine readable format. See [REP-149 Package Manifest Format Three Specification](https://ros.org/reps/rep-0149.html#license-multiple-but-at-least-one) for additional details. | ||
| * Your package must include a copyright at the top of every file. |
There was a problem hiding this comment.
I don't think we actively enforce this rule anywhere, other than the linters (which are opt-in). So I'd say let's drop this from the list of requirements for now.
There was a problem hiding this comment.
Agreed, AFAIK this is a requirement of some specific open source licenses, but not all.
| * Your package must include a copyright at the top of every file. | ||
| * A publicly available, open source, repository for your ROS package. | ||
| * While not required, we recommend that you create an account for ROS Discourse and subscribe to the [appropriate release topic](https://discourse.ros.org/c/release/16). | ||
| * If you real time chat would help you resolve an issue please join our [Discord Server] and join the `#infra-help` channel. |
There was a problem hiding this comment.
Suggested change
| * If you real time chat would help you resolve an issue please join our [Discord Server] and join the `#infra-help` channel. | |
| * If real time chat would help you resolve an issue please join our [Discord Server] and join the `#infra-help` channel. |
(also, this is missing the link to the Discord Server)
| Having your package included in a ROS Distro is a badge of quality, and we recommend that package developers strive to create packages of the highest quality. We recommend package developers review the following resources before submitting their package. | ||
|
|
||
| * [REP-2004 Package Quality Declaration](https://www.ros.org/reps/rep-2004.html)-- The ROS 2 TGC has created a quality rating system for ROS packages. These ratings should serve as a guide for package developers. We recommend package developers achieve a quality level of three or higher. | ||
| * Documentation -- at minimum ROS packages should include an extensive [README.md file, and API level documentation using the Sphinx documentation system](https://docs.ros.org/en/rolling/How-To-Guides/Documenting-a-ROS-2-Package.html). |
There was a problem hiding this comment.
I'd get rid of the "at minimum"; we don't actually require this, and while we recommend this, we don't enforce it:
Suggested change
| * Documentation -- at minimum ROS packages should include an extensive [README.md file, and API level documentation using the Sphinx documentation system](https://docs.ros.org/en/rolling/How-To-Guides/Documenting-a-ROS-2-Package.html). | |
| * Documentation -- it is recommended that ROS packages include an extensive [README.md file, and API level documentation using the Sphinx documentation system](https://docs.ros.org/en/rolling/How-To-Guides/Documenting-a-ROS-2-Package.html). |
| * [REP-2004 Package Quality Declaration](https://www.ros.org/reps/rep-2004.html)-- The ROS 2 TGC has created a quality rating system for ROS packages. These ratings should serve as a guide for package developers. We recommend package developers achieve a quality level of three or higher. | ||
| * Documentation -- at minimum ROS packages should include an extensive [README.md file, and API level documentation using the Sphinx documentation system](https://docs.ros.org/en/rolling/How-To-Guides/Documenting-a-ROS-2-Package.html). | ||
| * Maintainer Responsibilities -- the ROS 2 documentation includes a guide to [ROS package maintainer responsibilities](https://docs.ros.org/en/rolling/How-To-Guides/Core-maintainer-guide.html) that summarizes your responsibilities as an open source maintainer. | ||
| * Your package should strive to conform to the [ROS 2 Developer Guide](https://docs.ros.org/en/rolling/The-ROS2-Project/Contributing/Developer-Guide.html) and the [ROS 2 Style Guide](https://docs.ros.org/en/rolling/The-ROS2-Project/Contributing/Code-Style-Language-Versions.html). |
There was a problem hiding this comment.
This style is what we recommend, but quite a few package don't conform to it (not least of which because many people prefer clang-format over uncrustify). So I'd classify this one as a recommendation as well:
Suggested change
| * Your package should strive to conform to the [ROS 2 Developer Guide](https://docs.ros.org/en/rolling/The-ROS2-Project/Contributing/Developer-Guide.html) and the [ROS 2 Style Guide](https://docs.ros.org/en/rolling/The-ROS2-Project/Contributing/Code-Style-Language-Versions.html). | |
| * We recommend that your package conform to the [ROS 2 Developer Guide](https://docs.ros.org/en/rolling/The-ROS2-Project/Contributing/Developer-Guide.html) and the [ROS 2 Style Guide](https://docs.ros.org/en/rolling/The-ROS2-Project/Contributing/Code-Style-Language-Versions.html). |
nuclearsandwich
approved these changes
Oct 11, 2024
| * Your package must include a copyright at the top of every file. | ||
| * A publicly available, open source, repository for your ROS package. | ||
| * While not required, we recommend that you create an account for ROS Discourse and subscribe to the [appropriate release topic](https://discourse.ros.org/c/release/16). | ||
| * If you real time chat would help you resolve an issue please join our [Discord Server] and join the `#infra-help` channel. |
There was a problem hiding this comment.
The Discord link is missing.
Suggested change
| * If you real time chat would help you resolve an issue please join our [Discord Server] and join the `#infra-help` channel. | |
| * If you would like, you may join our [Discord Server](https://discord.com/servers/open-robotics-1077825543698927656) and ask questions in the `#infra-help` channel. |
I feel slightly hesitant to promise real time support.
|
|
||
| Having your package included in a ROS Distro is a badge of quality, and we recommend that package developers strive to create packages of the highest quality. We recommend package developers review the following resources before submitting their package. | ||
|
|
||
| * [REP-2004 Package Quality Declaration](https://www.ros.org/reps/rep-2004.html)-- The ROS 2 TGC has created a quality rating system for ROS packages. These ratings should serve as a guide for package developers. We recommend package developers achieve a quality level of three or higher. |
There was a problem hiding this comment.
Suggested change
| * [REP-2004 Package Quality Declaration](https://www.ros.org/reps/rep-2004.html)-- The ROS 2 TGC has created a quality rating system for ROS packages. These ratings should serve as a guide for package developers. We recommend package developers achieve a quality level of three or higher. | |
| * [REP-2004 Package Quality Declaration](https://www.ros.org/reps/rep-2004.html)-- The ROS 2 TSC has created a quality rating system for ROS packages. These ratings should serve as a guide for package developers. We recommend package developers achieve a quality level of three or higher. |
The Technical Steering Committee was the governing body when the quality levels were established although I don't recall what level of involvement they had in actually drafting and ratifying these. I recommend referring to these as ROS standards since they went through the REP process but I'm soft on it.
|
|
||
| * [REP-2004 Package Quality Declaration](https://www.ros.org/reps/rep-2004.html)-- The ROS 2 TGC has created a quality rating system for ROS packages. These ratings should serve as a guide for package developers. We recommend package developers achieve a quality level of three or higher. | ||
| * Documentation -- at minimum ROS packages should include an extensive [README.md file, and API level documentation using the Sphinx documentation system](https://docs.ros.org/en/rolling/How-To-Guides/Documenting-a-ROS-2-Package.html). | ||
| * Maintainer Responsibilities -- the ROS 2 documentation includes a guide to [ROS package maintainer responsibilities](https://docs.ros.org/en/rolling/How-To-Guides/Core-maintainer-guide.html) that summarizes your responsibilities as an open source maintainer. |
There was a problem hiding this comment.
The guidelines there I believe are for ROS 2 core maintainers rather than community package maintainers. As long as there's nothing too controversial in there they should be applicable but I don't know that they're for all maintainers by design.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Demo: cottsay/rosdistro#24
It might be nice to clean up some of the heading/bolding to make things a little more cohesive.