[Proposal] Improving the Autoware Repository Structure for New Contributors

[mitsudome-r]

Background

Currently, the main Autoware repository (https://github.com/autowarefoundation/autoware) appears empty, as it does not contain source code but instead relies on external repositories.

This structure has historical and architectural reasons, but for new contributors and industry partners, this leads to significant confusion:

• The repository appears inactive or incomplete at first glance.
• New users cannot identify where the actual code is located.
• Entry points are inconsistent across different repositories.
• Developers expect source code in the primary repo (following conventional OSS practices).
• Onboarding time increases, especially for companies evaluating Autoware.

These issues reduce Autoware’s approachability and hinder ecosystem growth. This proposal aims to:

• Reduce onboarding friction for new users and companies.
• Improve clarity of the repository structure through documentation and design.
• Align user expectations with the architectural layout (multi-repository design).
• Strengthen the perception of Autoware as a mature, well-organized OSS project.

Proposals

Option 1: Merge Autoware Core into the Autoware Meta-Repository

Move all source code from autoware_core into src folder in the autoware repository. Autoware Universe will be treated as extension to the Autoware repository and can be maintained via vcs .repos files.

Pros

• Simplest UX as people could just run colcon build out of the box to build minimal set of Autoware
• Eliminates “empty repo” issue entirely
• Single entry point for contributions and onboarding

Cons

• Major structural change → disrupts forks, CI, contribution workflows
• Requires migration planning & broad TSC consensus
• Reduced modularity

Option 2: Replace VCS with Git Submodule

Replace vcs with git submoulde. The meta-repo becomes a user-friendly bundle.

Pros

• Maintains modularity and separation of responsibilities
• Low-risk way to improve newcomer experience
• git submodule is well known than vcs tools

Cons

• Requires periodic sync or submodule updates
• Slight maintenance overhead vs. keeping the status quo
• CI integration becomes somewhat more complex (as we have different .repos files for different purpose)

Option 3: Add a src/ Directory with a README Explaining Where the Code Is

Leave the meta-repo empty, but create a src/ folder containing only documentation explaining the link to the code
Pros

• low cost
• Immediately solves the “empty repo” problem
• No impact on CI or contributor workflows

Cons

• Users cannot build Autoware directly from the meta-repo
• Less powerful improvements compared to other options
• Still multiple repositories → some complexity remains

Option 4: Keep Current State

Keep using vsc tools with autoware.repos files

Summary

Option	UX Improvement	Migration Cost	Maintains Modularity	Newcomer Friendliness	Risk
Merge Core into Autoware	Very High	Very High	Low	Very High	High
Submodule/Subtree	High	Medium-Low	Medium-High	High	Medium
README under src/	Medium	Very Low	High	Medium	Very Low
Keep current	Low	None	High	Low	Low

[xmfcx]

I highly suggest adding a README.md under src/ and improve the documentation where necessary.

The other options all bring unnecessary complexity and/or chaos.

Also let's move the .repos files under repos/ directory and do more tidying for the main repository.

❌ Merging autoware_core into autoware repository

We have already did so many migrations and created so much confusion in our history. GitHub autoware.ai -> GitLab Autoware.Auto -> GitHub autoware.core + autoware.universe -> autoware_core + autoware_universe.

Right now the roles of the repositories are clear, modular and we have precedent https://github.com/ros2/ros2
And the role of the main repository is to maintain dependencies for all the sub repositories, allow people to pick their modules.
For example, autoware_msgs is a core repository but it is separated, we don't talk about merging it with the main repository.

Also versioning autoware_core and autoware meta repository will be confusing too.

❌ Submodules

This makes us lose too much flexibility. One example is, "Submodules are designed to pin an exact commit." so we won't have nightly anymore. Making development harder.

vcs import < autoware.repos
vcs import < simulator.repos
vcs import < tools.repos

Right now we (and the autoware integrators) have modularity with what repos to pick. With git submodules, this wont be possible.

Also it will become complicated when people fork both this meta-repo and some sub-repos. If someone tested if where a submodule is modified to point to some other repo, please let us know.

[paulsohn]

One example is, "Submodules are designed to pin an exact commit." so we won't have nightly anymore. Making development harder.

@xmfcx I think you can do git submodule update --remote whenever you want, to retrieve the latest HEAD.
In .gitmodules, you can even specify which branch to follow using submodule.<SUBMODULE_NAME>.branch.
The nightly is then obtained in your local by syncing all versions using git submodule update --remote.
If you want to pin a version because of the consistency issue, then add submodule.<SUBMODULE_NAME>.update = none. This prevents the above command checks out the latest branch HEAD unless you explicitly add --checkout.

[paulsohn]

Gemini told me that

vcs import < autoware.repos
vcs import < simulator.repos
vcs import < tools.repos

can be done similar using submodule: place all repositories in autoware.repos into src/autoware/, repositories in simulator.repos into src/simulator/ and so on. You can fork Autoware non-recursively, and then git submodule update --init src/autoware/ to use only repositories previously from autoware.repos.

I'm unsure about this yet, so I will do some experiment soon.

[evshary]

I prefer option 3 because options 1 and 2 decrease modularity and increase complexity.
The detailed reason why I don't like it is just as Fatih mentioned, so I don't repeat it again.

As for option 3, I think we can not only tell newcomers where the code is, but also tell them how to get the code.
I suppose the newcomers are not familiar with vcs and struggle to find a way to get the code.
It would be great to mention this in the README. My two cents.

[felixf4xu]

yes, list the https://autowarefoundation.github.io/autoware-documentation/main/installation/autoware/source-installation/ in the README to be the first step.

[paulsohn]

Definitely the short-term goal should be option 3, but I don't get why submodule should be hated this much.

I don't think submodule ever compromises our development flexibility, but even if it did, I would still prioritize observability over flexibility as we're dealing with safety-critical software.
For instance, with vcs status we can't tell whether the entire super-repository is dirty or not by one-liner. It will output so many lines of HEAD detached at <SHA>, unless you filtered it using grep. It doesn't even work on the project base, but only in src.
Also, other third-party version management tools, such as git graph (VS code extension) supports git submodule but obviously not vcstool.

[xmfcx]

For submodules, I would like to see a reference implementation of this as a separate repository and see if it can support all the use cases we have with vcs.

Since our .repos files are well defined, it should be possible to be done by anyone.

Using vcs, I can keep the sub-repositories intact while jumping up and down commits in the main repository. And only update the vcs import when I want to. But when submodules are involved, it will make it more bulky to change branches/commits etc.

I haven't used submodules for a long time so this is why I'm recommending to create a mirror of the main autoware repoistory using submodules so we can try and see how it compares objectively.