Repository navigation
3di | Add area and related_scope metadata for related packages lists - #3309
Open
kacperbojakowski-3di wants to merge 2 commits into
Open
kacperbojakowski-3di wants to merge 2 commits into
kacperbojakowski-3di wants to merge 2 commits into
Conversation
Signed-off-by: Kacper Bojakowski <kacper.bojakowski@3di-info.com>
kacperbojakowski-3di
changed the title
ABI Compliance Check❌ Verdict: incompatible
❌
|
Collaborator
|
I don't like the approach for several reasons.
|
Author
|
Thanks @jmachowinski, both fair points. There is a curated list. It lives in On packages declaring themselves core, the default is community, and the grouping is only read on the docs side, so moving to a curated list wouldn't need anything undone in the packages themselves, but I'll leave that one with OR. cc @tfoote |
Contributor
|
I think that there's to generally space to improve on this with validation etc. But we can't know all the potential tags people would want to use up front. And yes we can potentially curate and restrict packages from certain tags like core. But to start let's rely on our community behaving with good intentions and use social processes to manage it until it doesn't work. This is one of many that were pushing ahead with this mechanism. We can continue to improve and evolve things. But this will help us get to better docs with what we have so far. |
Collaborator
@kacperbojakowski-3di just wrote above, that there is a list of tags, and that all other ones are being ignored anyway.
What am I missing here ? Core packages are kind of static. Is only about 50 packages and they almost never change. I don't see any good reason to have a complicated dynamic way of determining them. From my point of view, this is unnecessary complicated, clutters our package.xml and has potential for misuse. Apart from this, I am a bit confused about the scope of the documentation overhaul. Until now I was under the impression that only docs.ros.org should be overworked. E.g. make the tutorials better an more beginner friendly, make it so that people can actually find workgoups etc. I was not aware that an overhaul of index.ros.org was also in the scope of this work. |
fujitatomoya
reviewed
Oct 8, 2026
fujitatomoya
left a comment
fujitatomoya
left a comment
Collaborator
There was a problem hiding this comment.
i don't have a fundamental objection to this approach if TGC made this decision.
but imo @jmachowinski points stand, this probably generates more maintainability than benefits, i guess.
especially, i do not like this part if i am not mistaken.
so on the docs side anything outside it is flagged as an error.
this means, typos in the some package.xml can break the documentation? i do not think this is acceptable, it should be checked and validated when the package.xml is submitted?
sloretz
reviewed
Oct 9, 2026
Comment on lines
+65
to
+66
| <area>client-libraries, framework</area> | ||
| <related_scope>core</related_scope> |
Contributor
There was a problem hiding this comment.
Suggested change
| <area>client-libraries, framework</area> | |
| <related_scope>core</related_scope> | |
| <x-area>client-libraries, framework</x-area> | |
| <x-related_scope>core</x-related_scope> |
IIUC, since this is a new tag that we're trying out for the docs I recommend making the tag name more clearly experimental. An x- prefix seems like a good idea matching https://www.rfc-editor.org/info/rfc6648/
Contributor
There was a problem hiding this comment.
Looks like https://www.ros.org/reps/rep-0149.html#export recommends prefixing with a package name prefix.
Suggested change
| <area>client-libraries, framework</area> | |
| <related_scope>core</related_scope> | |
| <ros2_documentation_area>client-libraries, framework</ros2_documentation_area> | |
| <ros2_documentation_related_scope>core</ros2_documentation_related_scope> |
Contributor
There was a problem hiding this comment.
I do think that this naming approach is better so that people can find the content better.
Author
Contributor
For areas, in the current state yes. We're focused specifically on ros2_documentation builds. But looking beyond our initial rollout this sort of tagging should be something that all packages can do. In the broader ecosystem and as you think about people who might have a private instance of this with their own custom packages we can't have a centralized preordained list of tags without maintaining that list of tags becoming a very large challenge. I'm not sure if the related_scope is also listed somewhere, note that core is not in that list. https://github.com/ros2/ros2_documentation/blob/71492ab3295315cf9546eed895dc3c766ee51d62/tools/enhance.yaml#L20-L42
A typo in a tag here will lead to a package being missassociated. It won't "break" the documentation. This is the same as any other key in the package.xml if you misdeclare a dependency it will point to the wrong thing too. Most maintainers notice it or get it ticketed after it deploys more widely and the error becomes more obvious. You may be first in class of a type, for which there's no others. That's a potentially valid situation.
Core is a convenient example of something that is clearly defined and can provide us with a clear example of how to do grouping initially. Obviously we could make something to special process it. But with this mechanism we're enabling a class of categorization, using core as an example. Versus the goal is to categorize core. We're currently only targeting the documentation builds, but putting these classifications into the package.xml means that it will get into the rosdistro cache and from there it can trivially be picked up by many other tools including the rosdistro library and into rosindex too. The reason we have the exports section is to enable dynamic and explorative usages for specific tools. If we do find this to be very useful and something that we should standardize there's talk of package.xml format 4. But until we try things out I definitely wouldn't want to propose this sort of change into the core specification. If there's a few extra tags here while we experiment it does have extra content, but removing it down the line if the experiment fails is not hard either. This is like adding 2 lines of description to a package which has only a single sentence description would be very reasonable/probably much better. This is adding 2 lines of structured documentation which helps people find it. |
kacperbojakowski-3di
added a commit
to kacperbojakowski-3di/ros2_documentation
that referenced
this pull request
Oct 16, 2026
Address Shane's feedback on ros2/rclcpp#3309 to have the names in export prefixed.
Use REP 149 package-name prefixes for the docs export tags, matching feedback on ros2#3309 / ros2/ros2_documentation#7240. Signed-off-by: Kacper Bojakowski <kacper.bojakowski@3di-info.com>
This file contains hidden or 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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
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.
Description
Adds
<area>and<related_scope>torclcpp'spackage.xmlso the related packages lists in #7240 can match this package. Those lists read exports from the rosdistro cache. Nothing released declares them yet, so the lists are empty. This is one core package as a worked example.Metadata added
In the existing
<export>ofrclcpp/package.xml:<area>: which docs pages list the package (most specific first).<related_scope>:coreorfederation(missing is treated as community).Why these values
client-libraries, frameworkmatches docs pages that already use:area: client-libraries, framework.coreputs it under Core ROS packages rather than community.Why this is safe to add
<export>is the passthrough container for tool-specific metadata, and tools are expected to skip any export tags they don't recognise (REP 140). Nothing in the build reads these two, so there's no effect on howrclcppcompiles or runs, and no ABI impact. This is all just for the docs.Scope and next steps
Limited to
rclcppon purpose, as an example to look at before this goes wider. I'll be adding the same exports to the other core packages. Each one shows up in the docs after relase and cache refresh.Dependencies
Visible to users once #7240 and #6981 land, and this
rclcppchange is released (docs read the released cache, not source).Changes
rclcpp/package.xml: add<area>client-libraries, framework</area>and<related_scope>core</related_scope>.Additional Information
Issue: #6991