Added multi-branch support for master

[leander-dsouza]

Note

Please refer to #763 after this to get a better understanding of how to add future distros (e.g. kilted).

Basic Info

Info	Please fill out this column
Ticket(s) this addresses	#654

Description of contribution in a few bullet points

nav2_multi-branch-support-master.mp4

• Incorporated sphinx-multiversion to extend builds for different branches.
• A dropdown menu has been added supporting master.

How to test this change?

• Merge this branch to master locally, and run make multiversion according to the updated README.

Future work that may be required in bullet points

• The kilted branch needs to be created after this PR is merged.
• Mergify bots can be included after the dropdown menu supports rolling/master and kilted.
• (Optional) The master branch can be renamed to rolling for readability in the Docs.

[SteveMacenski]

Some major comments:

1. Can this be moved to the main area before the search bar? We have a latest declaration. Seems like a good place for that to be replaced with main and the drop down for other distros.
2. What is the workflow for changes reflected on different distributions? If I have updates I backport to humble, for example, what is the workflow for this change to have updates reflected on Humble's version of this website? Keeping these up to date is paramount if we're going to do this, which means we need to have process or automation tooling that does this. That workflow should be put in place before anything else is done. Ideally, something that puts the minimal amount of overhead on maintainers.
3. If we do such a thing, what recommendations do you have for ripping out the current state of Nav2 back to previous check points like Humble or Jazzy to have those versions supported?
4. Yes, please change master to rolling. I don't want to change the branch name right now, but we can if that is strictly required. Can that not be changed as a setting?
5. I ran into someone the other day that introduced me to ascii docs and got me thinking: with the new gen AI tools, I bet we could migrate this website to another format which might come with some added benefits. Before going too far on making major changes to readthedocs, I'm curious about other modern software documentation formats (ex this looks really nice https://moveit.ai/install/ & https://docs.anthropic.com/en/docs/get-started) which might be worth the investment to doing work as part of a larger migration if there are benefits

Refs

• https://docusaurus.io/
• https://asciidoc.org/
• https://docs.antora.org/antora/latest/
• squidfunk.github.io/mkdocs-material/

[leander-dsouza]

Some major comments:

Thank you for the detailed feedback, Steve :)

1. I have moved the version dropdown menu to be below the Nav2 logo, and have added a white border in order to distinguish it from the background.

   nav2_dropdown.mp4

2. I have added a Mergify configuration to assist in backporting to kilted, jazzy and humble.
   The make multiversion builds on the updated CircleCI configuration, ensures that whenever anything is published to one of the supported branches, the whole docs gets built again with all the branches combined.

   This is the folder structure (kilted, jazzy, and humble not added yet):

   

   This ensures all the supported branches are built using make multiversion.

3. I think we can start with kilted and move backwards. Some of the Immediate steps include:

   • Reduction of the Migration Guide to just Jazzy to Kilted.
   • The Roadmap section could be distro-specific as well.
   • The API Docs website (which is present on the left sidebar of the homepage) could be targeted to show Nav2 and ROS2 APi for the selected distro.

   For a more detailed distro-specific guide, we can follow the migration guide and adjust each supported branch in incremental changes.

4. Yes, I have modified the default version dropdown menu to show rolling by default. No branch name change is necessary; it was just an optional suggestion for the rename.

5. Thank you for sharing the reference links about various documentation websites. I really like the MoveIt documentation for the Installation; it is definitely easier to look at and follow. However, the tutorial and subsequent How-to-Guides section are made in Sphinx.

   The other documentation links also seem interesting. I personally prefer how vibrant uv website looks. I think we can explore Mkdocs-material in the future, as it is purely HTML.

[SteveMacenski]

I have moved the version dropdown menu to be below the Nav2 logo, and have added a white border in order to distinguish it from the background.

Yes, I have modified the default version dropdown menu to show rolling by default. No branch name change is necessary; it was just an optional suggestion for the rename.

Nice! 👍

I think we can start with kilted and move backwards

👍 Probably wise.

What is the workflow for changes reflected on different distributions?

I think more than just the automations, but the actual maintainer workflow. Right now, I merge into main in Nav2 and periodically will go through the changes made over the last 4-6 weeks to cherry pick commits that don't break ABI/API to each actively maintained distribution. If I have to add in documentation backports and updates simultaneously, that's alot to juggle. I'm curious what you think is a sensible workflow that makes sure these remain in-line with each distribution and try to find a mechanism that isn't as Steve-not-fucking-up dependent.

The 4-6 cherry pick event is something I like since I can bulk process out a bunch of distros and deal with merge conflicts all at once locally, versus using the backport bot in Nav2 to do it and then have to deal with the github UX for resolving complex merge conflicts. Plus, I test locally before pushing the updates to make sure things work and I'm confident in running a release for that distro that day.

I'm trying to think about adjustments:

• For every commit I'm seeing in the main's git log, go back to Nav2 docs and try to find them each individually to add the backport tag to. Maybe keep a running spreadsheet somewhere of the doc updates to make the find operation easier. The issue here is human error of missing some
• For any doc PRs we think we'll backport, just backport it when we merge in the original PR? The problem is that it'll be out of sync and in case it turns out it cannot be easily backported, it might remain out of sync indefinitely.
• Change my workflow to backport immediately all PRs that can be backported and do so with the documentation as well. The problem here is that if there are bugs in main, I want them to have some soaking time in the bleeding edge development branch before it gets distributed for released distributions which have some promise of attempted stability. Reverting or future fixes to those bugs that break ABI/API would add a great deal of complexity both to Nav2 and the documentation

I generally have wanted to support multiple distributions for documentation, but I haven't thought of a good way of really maintaining it that (a) isn't a huge process burden since releases for distributions is already a nearly-all-day task and (b) isn't hugely human error prone making it unreliable. The first idea seems like the best I have so far. Some of your thoughts as the author might be nice 😉

Something I had thought about was adding an "Added in X" distro field for every parameter. That would give some versioning on a single website, but I suppose has a similar issue as my first idea with keeping it inline with backports.

The other documentation links also seem interesting.

Yeah, I think it was something I was curious to experiment with. I'm not sure how value generating it is, but it would look prettier, which I suppose is some value in it of itself. I've been kind of wanting a revamp for the docs.nav2.org landing page / videos / etc and these new formats came to mind that seem better to support media-first initial pages

[leander-dsouza]

If I have to add in documentation backports and updates simultaneously, that's alot to juggle. I'm curious what you think is a sensible workflow that makes sure these remain in-line with each distribution and try to find a mechanism

My suggestion is to add a potential distro-label to any PR that gets merged into the master/rolling branch of the Docs.
For instance, if the change were to be ported over to kilted and jazzy, these can be labelled as potential-kilted and potential-jazzy.

After the main branch of Nav2 is sufficiently soaked or marinated for stability, whenever you cut a release for kilted or jazzy, these potential labels on the Docs can be removed upon successful merge through mergify.

If any change is reverted from the main branch of Nav2 due to bugs or instability, then when the corresponding PR to the Docs gets reverted, these potential labels can be deleted.

To make the whole process easier for contributors and maintainers, we can add a Pull Request Template detailing the potential branches that the change can be merged into.

I feel this method is better because of the following reasons:

• We do not need to maintain a spreadsheet, as we can simply look for potential labels whenever we cut a release.
• The backport PRs do not need to be merged immediately, and hence bleeding-edge features can marinate until the new release.

Yes, I believe the landing page can be inspired by MoveIt or uv, as it prioritises the functionality of the tools and installation immediately on the homepage.

[SteveMacenski]

I spent a bit of time mulling this over and I think what I'm leaning towards is kicking the can down the road. If the intent is to update the documentation format in the short to medium term future, then adding multiple heads to track is going to double-triple-quadruple the amount of manual QA and adjustment work for the new formatting. I'd rather wait for multi-branch support with a new format than doing beforehand.

In terms of process, I think that's towards a better solution, but still very human error prone. Other than moving the docs back into the Nav2 source directly so code changes + doc updates are all in one place for backports to carry both, I don't see a real bullet proof solution. I was thinking that on a backport branch, I could ask an LLM to look at the cherry picked commits, find their PRs and find associated documentation PRs and give me them as a list. We could add that as a github template parameter of both the Code PRs and the docs PRs so that hopefully someone doesn't miss it twice. Also if its just in the PR template fields, I could personally just click on those docs when I'm doing the backports, but the main issue I see with that is that many people open up the docs PRs long after the original PR was opened in response for my request for include doc updates. So relying on the linkages rather than PR body fields seems better.

I think the gh cli has some way to identify linked PRs programmatically, so instead of relying on AI, we could actually just write a simple bash script (maybe with AI 😆 ) to use that CLI to scrape back any local commits ahead of origin, get their linked PRs and list any from docs.nav2.org for me.

That actually sounds perfect. That script could even be run in as a mergify command/github action in the Nav2 backport PR to run as a job and then automatically open the associated docs backport PRs by adding the 'backport' tag on the docs PRs that it contains (i.e. CI job runs script to ID the docs PRs for the backported Nav2 commits, then on those docs PRs, automatically tag them with a backport-kilted tag which triggers mergify to open backport PRs. Then I just need to review those bulk PRs and merge them).