How to move this forward

[rkent]

I'd like to hear from @tfoote @nuclearsandwich and @kscottz on this if possible.

I've now largely finished my update to rosdoc2, see https://github.com/rkent/rosdoc2/tree/rkj-main The bad news is that I am 41 commits ahead of this repo. I know that reviews are hard, and everyone is busy. But at the current rate of reviews and landings, it would take another year to get this landed. Frankly, I'm getting tired of working on it, and would like to move on. I appreciate the reviews I have had, really I do, and I know how hard they can be since I've been a senior reviewer myself. But still, I need a plan. I've tried to trickle PRs into this repo, but it really gets hard to maintain a fork 41 commits ahead of main, while backporting into main.

There are also issues beyond the patches into this repo. In order to move forward myself, I run a nightly build of my current rosdoc2 on rolling, available at http://rosdoc2.rosdabbler.com. That build has docs for 1373 packages (with 3 failing), while the "official" has 1082 packages. But you can see how things look with the current rkent/rosdoc2, and that things don't fail horribly.

The difference in number is:

• I am aggressive about including packages, not just limiting to the doc: repos in rosdistro
• I have a curation file in place, where I can fix settings of packages that are causing failures, or otherwise resulting in sub-standard documentation
• I reclone packages from release: that don't have package.xml until they are built (about 10 packages).

Those are policy issues beyond this current repo that would mostly be addressed at the build farm level, but it is part of the overall goal of getting the best available documentation of the most packages.

I don't really know the culture of ROS well enough to know the right forum to discuss this. Is this it? Should I be sending emails? Discord or discourse messages?

I'm mostly on vacation next week, still probably able to respond but not doing any new development.

Looking forward to discussion and a plan.

[tfoote]

Yes, sorry you're being very productive and we're definitely behind on the reviews. I greatly appreciate you doing that extra work I know how much it takes to maintain that differentiation. Your work and contributions have been noticed by much of the team and I think that it might be worth discussing if you'd be interested in having a more formal project role.

With respect to what gets indexed there have been many times in the past when we've had efforts to extend what's documented and for a little while it can be true that we can extend the coverage. However these parallel lists invariably fall out of date due to the effort required to maintain them over time. We've spent a lot of effort to develop a system to manage the rosdistro and it forms the foundation of the indexing. As the distro maintainers we work to facilitate the indexing and building of the things that maintainers submit. In general though only the maintainer knows the correct version to document or index. And we rely on getting that information from them via the rosdistro.

Now some of the things that you've called out to make the tools more robust would be great to consider. We want to make it such that it's easier for maintainers to add and contribute content. If the tools are more robust to missing information etc that can help.

I think that also making it clearer where information comes from would be very helpful, to make it simpler for people to submit to the index as well as update information there.

For example we could make adding to the index easier with more web based worflows like this: https://index.ros.org/contribute/add_repo/ and maybe a button "Propose a change" to the metadata field on index.ros.org.

For the examples without a doc entry, we could improve our release toolchain to do things like encourage people to more actively encourage maintainers to submit the doc entry. And possibly do things like have a 404 message in place saying "doc entry missing in rosdistro, please submit one here " on the site such that maintainers and users know what's necessary to add it.

[rkent]

"it might be worth discussing if you'd be interested in having a more formal project role"

I signed up yesterday to come to ROSCON 2024, so it might be good to meet and discuss this in person there. In general though, I think it would be healthy for ROS to have more active people in ros-infrastructure that are not tied to Intrinsic. Nothing against Intrinsic, but I have been through this before and ended up being the person having to reorganize Thunderbird governance and funding after they were abandoned by Mozilla, so I know the risks of over-reliance on a single company.

As for more authority within the documentation repos, (rosindex and rosdoc2), it really only helps my progress if additional reviewers could be recruited form outside the existing core team. I don't know enough about the community to know if that is feasible or not.

"With respect to what gets indexed ...": I'd like to discuss this, but not sure of the right forum. Do you have a suggestion? I'm not promoting something independent of rosdistro, only that the build farm be aggressive about trying to find something to document.

[nuclearsandwich]

I signed up yesterday to come to ROSCON 2024, so it might be good to meet and discuss this in person there.

This is great news! I'm looking forward to continuing the discussion at ROSCon.

I think it would be healthy for ROS to have more active people in ros-infrastructure that are not tied to Intrinsic.

I'm in complete agreement with you, the more varied the funding sources and objectives of infrastructure project members, the more robust the project is to all manner if interruptions or distractions. I do want to say that our maintenance and review capacity has been a challenge since before any of us joined Intrinsic and that from a total membership perspective, the Infrastructure project is about 50:50 Intrinsic-affiliated members and not.

As for more authority within the documentation repos, (rosindex and rosdoc2), it really only helps my progress if additional reviewers could be recruited form outside the existing core team. I don't know enough about the community to know if that is feasible or not.

There's two direct angles and one indirect angle that I think would be useful here. As a maintainer/committer on projects, you would be able to make merge decisions based on reviews from either other maintainers or community members. "Gray check marks are as good as green ones" when getting a co-maintainer's review is impractical. So you'd become one more person who can focus on specific projects and determine whether a community review is sufficient. The other side is that right now, it's much easier to get review within the project than it is for us to do community review. Being a committer would make you a participant in our internal cross-review discussions. The last indirect benefit would be the opportunity to see what all the project members are working on and having a better understanding of how the documentation projects fit into that. As I'm sure you know from contributing to Thunderbird, there's often more that needs doing than there are people to do it and different teams and people have different methods of handling that.

There's actually no requirement to be part of the PMC to join our meetings (although public observers are not asked to request agenda time in advance if they'd like to talk rather than observe). If you're able to join, our project meetings are open to the public and held at Mondays 9AM US/Pacific (listed on the OSRF Official Calendar

[kscottz]

@rkent Great meeting with you today. Can you reach out to me at ***@***.***? I want to schedule some time to move this and your other pull requests forward.

…

On Thu, Oct 3, 2024, 20:50 Steven! Ragnarök ***@***.***> wrote: I signed up yesterday to come to ROSCON 2024, so it might be good to meet and discuss this in person there. This is great news! I'm looking forward to continuing the discussion at ROSCon. I think it would be healthy for ROS to have more active people in ros-infrastructure that are not tied to Intrinsic. I'm in complete agreement with you, the more varied the funding sources and objectives of infrastructure project members, the more robust the project is to all manner if interruptions or distractions. I do want to say that our maintenance and review capacity has been a challenge since before any of us joined Intrinsic and that from a total membership perspective, the Infrastructure project is about 50:50 Intrinsic-affiliated members and not. As for more authority within the documentation repos, (rosindex and rosdoc2), it really only helps my progress if additional reviewers could be recruited form outside the existing core team. I don't know enough about the community to know if that is feasible or not. There's two direct angles and one indirect angle that I think would be useful here. As a maintainer/committer on projects, you would be able to make merge decisions based on reviews from either other maintainers or community members. "Gray check marks are as good as green ones" when getting a co-maintainer's review is impractical. So you'd become one more person who can focus on specific projects and determine whether a community review is sufficient. The other side is that right now, it's much easier to get review within the project than it is for us to do community review. Being a committer would make you a participant in our internal cross-review discussions. The last indirect benefit would be the opportunity to see what all the project members are working on and having a better understanding of how the documentation projects fit into that. As I'm sure you know from contributing to Thunderbird, there's often more that needs doing than there are people to do it and different teams and people have different methods of handling that. There's actually no requirement to be part of the PMC to join our meetings (although public observers are not asked to request agenda time in advance if they'd like to talk rather than observe). If you're able to join, our project meetings are open to the public and held at Mondays 9AM US/Pacific (listed on the OSRF Official Calendar <https://calendar.google.com/calendar/embed?src=agf3kajirket8khktupm9go748%40group.calendar.google.com&ctz=UTC> — Reply to this email directly, view it on GitHub <#144 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAHMFCWQNUQPZKSQ6ODTATTZZWGXBAVCNFSM6AAAAABNBBIY6SVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDGOJSGA4TSNZTHE> . You are receiving this because you were mentioned.Message ID: ***@***.***>