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.