The current directory structure in Drake is organized to (1) group functional components, (2) limit dependencies, and (3) prevent circular dependencies.
All code that implements core functionality in Drake must adhere to the strict code standards described in Developer Notes <developer_notes>, and must have unit test coverage via code implemented in a test subdirectory immediately below the core implementation.
To promote rapid development of research ideas within the code base, we allow for some exceptions to this rule for experimental code. This includes any subdirectory labeled dev and directories with a special README.md file describing the protocol for that directory. For PRs that affect only these experimental directories, one feature review is sufficient; platform review is not required. If build or test targets in these directories break, and the PR author or on-call build cop cannot trivially resolve them, a GitHub issue will be assigned to the author of the code. If the issue is not resolved within 24 hours, the core development team may disable the offending targets.
The BUILD.bazel rules for special directories must live within the directory itself, not a parent directory. (For example, foo/BUILD.bazel must not say srcs = ["dev/bar.cc"],; instead, foo/dev/BUILD.bazel must exist and must say srcs = ["bar.cc"],.) This ensures that all dev code has a package name that clearly denotes it as such.
We would like to avoid circular dependencies in the source code tree. For example, some code in drake/systems depends on code in drake/solvers, so code in drake/solvers should not depend on drake/systems.
The drake/examples directories are logically after all of the core libraries in drake. test directories located throughout the code are logically last in the dependency tree -- they are allowed to depend on any of the other directories. For example, test code is allowed to use models/code from the examples directories to test core functionality, as long as that dependency is explicitly declared in the build system rules for that test.