[ros-users] [Discourse.ros.org] [Autoware] Source code layout revision

Geoffrey Biggs via Discourse.ros.org ros.discourse at gmail.com
Thu Mar 7 08:05:39 UTC 2019

As I said over in the [repositories topic](https://discourse.ros.org/t/splitting-the-autoware-ai-repository-and-changing-the-organisation/8139),

> related to splitting the repositories is reorganising the package structure

This is the topic for discussing that.

The current structure has several problems that make it hard to manage and maintain, let alone understand for new contributors, such as:

- It mixes several software projects in a single repository when they should be in separate repositories related by an organisation. For example, nodes for driving a car, and a tablet-based UI.
- You have to dig down a long way to get to the actual source code, e.g. five directories deep to get to the messages, and often several more to get to node source files.
- The layout in no way conforms to the [proposed best practice for ROS 2 repositories](https://github.com/ros-planning/navigation2).

We need to reorganise packages as part of splitting up the repositories. However we should also take the opportunity to reorganise the files as well. This includes cleaning up the structure of a package, moving files to other packages, splitting and/or merging packages, and so on.

@shinpei0208 has been pushing a repository reorganisation that you can find <a class="attachment" href="/uploads/ros/original/2X/9/9171a5195853566dbe3e8b18eaf76379f7386009.pdf">here</a> (188.9 KB). However, this preserves the problems stated above so I am not in favour if adopting it wholesale.

I think that reorganising the packages and the code is something to be tackled over time during the 1.12 iteration, and possibly into 1.14 as well. It is not something to hurry. It is also something we should do a little at a time, not all at once. So I am not concerned with having a plan ready to go by the 14th of March for the 1.12 release startup period. However I do want us to start talking about it now and gradually work towards a consensus.

In particular, I want a consensus on the guidelines for how to organise a repository and how to organised a package. A good starting point is the ROS 2 guidelines for [organising a repository](https://index.ros.org/doc/ros2/Contributing/Developer-Guide/#repository-layout) and [organising a package](https://index.ros.org/doc/ros2/Contributing/Developer-Guide/#package-layout). Also worth consulting are large projects like [MoveIt2](https://github.com/ros-planning/moveit2) and [navigation2](https://github.com/ros-planning/navigation2), although both are under active development so consider that their layouts may change.

Based on the guides above and the fact that we want to transition to ROS 2, here are some principles I have come up with. I will edit these as the discussion continues to reflect the developing consensus.

Repository guidelines:

- If a repository is intended to contain a single package, that package should be at the top level directory, not in a subdirectory.
  - I do not expect us to be in this situation, but for completeness I've included it.
- In general, the repository should contain packages in a flat structure.
- If there is an argument for it, a repository may contain one level of subdirectories that divide up packages by some categorisation. However only one level is allowed and the subdirectories are purely for repository organisation.

Package guidelines:

- Follow the [ROS 2 recommended layout](https://index.ros.org/doc/ros2/Contributing/Developer-Guide/#id29).
- Package content is determined by relatedness, not by a rule such as "only nodes in a package" or "this package must only contain a library, the nodes go elsewhere."
- If a package contains a library that has no ROS dependencies, it should be a pure CMake package such that it could be built on its own using non-ROS, non-colcon tools.
  - Packages like this are prime candidates for being their own repository and treated like any non-ROS software.
- Messages go in their own package, in keeping with ROS 2 best practices.
- URDF files and other hardware description-related stuff should go in its own package. For example, the URDF for a Velodyne should be its own package.
- Launch files not related solely to the nodes in one package (e.g. a launch file to bring up all of Autoware, or a particular perception pipeline) are candidates for having their own package.

Please add any additional guidelines or modifications to these ones in the comments below.

[Visit Topic](https://discourse.ros.org/t/source-code-layout-revision/8191/1) or reply to this email to respond.

More information about the ros-users mailing list