Dynamic object following tutorial out of date / history aware documentation

[moooeeeep]

I noticed that the API used to provide a custom behavior tree config in the dynamic object following tutorial no longer exists:

ros2 launch nav2_bringup tb3_simulation_launch.py default_bt_xml_filename:=/path/to/bt.xml

According to the parameter descriptions given here this was changed since galactic. After some research we find hints in the migration guides too.

I'd like to suggest to at least add a hint to the tutorials highlighting the release version / ROS 2 distribution they were written for, or last tested with, and a disclaimer that subsequent releases might break (or already broke) compatibility.

---

At least from my perspective this highlights a more general issue with the documentation. Not sure how much effort this would entail, but can we get something like a distribution selection option for users stuck to LTS releases, that would serve an "old" state of the documentation, e.g.

• https://navigation.ros.org/humble/configuration/packages/configuring-bt-navigator.html
• https://navigation.ros.org/iron/configuration/packages/configuring-bt-navigator.html
• https://navigation.ros.org/rolling/configuration/packages/configuring-bt-navigator.html

Having to double check multiple migration guides (or having to reverse engineer the source code) for every other lookup feels feels disappointing.

[SteveMacenski]

You're definitely not wrong :-) Its a matter of contribution I think for folks to identify these problems and submit PR s to fix them! Please submit a PR and I'm happy to review / merge to fix this issue :-) Documentation takes a village!

All documentation is targeting Rolling, but you have a good point that if we're going to have some issues with versioning, it might be good to be explicit about what the tutorial was last written for/tested against. Some of these are temporary growing issues as the project matures and we stop making big architectural changes that introduce issues like you mention.

[moooeeeep]

I know :)

I just grew up used to big projects that somehow manage to achieve this (numpy, scipy, matplotlib, scikit-learn, django etc), in blissful ignorance of how much effort it is to set up or maintain.

If we could get version tags to the docs that roughly correspond to the version tags of the main repo, or distro branches (in case we ever want to submit distro-specific PR to the docs). That would be a good start I guess. Even if we may still need to download and self-host.