Rethink ROS 2 integration template

[dvdmc]

This issue comes from gazebosim/ros_gz#708, where we are currently discussing how to integrate ros_gz READMEs with the docs and improve the docs in general. This specific issue comes from my conversation with @j-rivero quoted here:

@dvdmc: Question regarding integration template: bringup, description, and gazebo are related to specific robots or platforms. In research groups they could potentially include their specific robots, sensors... However, in this tutorial they are associated with a "Project". I would say that in research groups, bringup, description, and gazebo are usually dependencies spread across other repositories external to the project. Would it make sense to structure the template tutorial around the concept of the these three folders and treat them independently from a "Project"? Then, focus instead on how they should be added as "external" dependencies to any project.

@j-rivero: We can re-think this indeed. Could you please open an issue in the template repository so we discuss it there?

My idea would be to treat [name]_bringup, [name]_description, and [name]_gazebo more generally. Explain what they should contain with linked examples to established packages, and not necessarily attached to a project. I believe this maintains the principles while being a more flexible approach that focuses on the essence of the three packages existing somewhere. Whether they are included in a project or maintained as separated and imported to different projects is specific to the user, company, or research group use case.

[j-rivero]

Let me add a bit of context: we are speaking about this document https://gazebosim.org/docs/latest/ros_gz_project_template_guide/ that refers to this repository https://github.com/gazebosim/ros_gz_project_template, is this correct?

My idea would be to treat [name]_bringup, [name]_description, and [name]_gazebo more generally. Explain what they should contain with linked examples to established packages, and not necessarily attached to a project.

When we refer here to 'project', what do you have in mind? I think that the template approach is to have the three packages (bringup, description, gazebo) and add a fourth one that encapsulates an application. I think that it could be the better approach for small-scale for ROS+Gazebo "projects". For mid/large-scale projects a multi-repository approach would be better indeed. We can add a mention about this in the document.

[dvdmc]

Let me add a bit of context: we are speaking about this document https://gazebosim.org/docs/latest/ros_gz_project_template_guide/ that refers to this repository https://github.com/gazebosim/ros_gz_project_template, is this correct?

Correct.

When we refer here to 'project', what do you have in mind?

I use the 'project' in a similar way than the tutorial. It refers to the template ("example of a project ..."). The idea that I, as a user, got when reading it is that I'm supposed to start any of my "apps" by cloning the template.

Currently the tutorial starts with directly cloning the template before explaining the motivation, which felt like the standard practice for every project that involves Gazebo. However the approach of our lab will be to have a repository for each robot that includes methods for running robot drivers, sensors, and basic localization/mapping and planning functions in real-world and simulation (bringup+description+gazebo). Then integrate this within any project that needs it (my new fancy planner). I think the template should refer and contain only the first, similar to Msg packages.

I think that the template approach is to have the three packages (bringup, description, gazebo) and add a fourth one that encapsulates an application. I think that it could be the better approach for small-scale for ROS+Gazebo "projects". For mid/large-scale projects a multi-repository approach would be better indeed. We can add a mention about this in the document.

Agree. I would modify slightly the docs to begin with the motivation for those three packages. Then show the template project (maybe withour the _app package) and mention a more "sustainable" practice with multi-repos. How does that sound?

[j-rivero]

I use the 'project' in a similar way than the tutorial. It refers to the template ("example of a project ..."). The idea that I, as a user, got when reading it is that I'm supposed to start any of my "apps" by cloning the template.

Currently the tutorial starts with directly cloning the template before explaining the motivation, which felt like the standard practice for every project that involves Gazebo. However the approach of our lab will be to have a repository for each robot that includes methods for running robot drivers, sensors, and basic localization/mapping and planning functions in real-world and simulation (bringup+description+gazebo). Then integrate this within any project that needs it (my new fancy planner). I think the template should refer and contain only the first, similar to Msg packages.

Fully agree with this. We can mention the motivation, the scope and what to do in larger projects in the document.

Agree. I would modify slightly the docs to begin with the motivation for those three packages. Then show the template project (maybe withour the _app package) and mention a more "sustainable" practice with multi-repos. How does that sound?

Please go ahead 🚀