Repository Structure

Repository structure

Structure is documentation that cannot go stale. A newcomer landing on the root should be able to tell what the project is, how to run it, and where the code lives, without asking.

Method

1. Make the root readable. A handful of files with obvious purposes, since a root with forty entries communicates nothing (see documentation-for-adoption).
2. Put the community files where the platform expects them. Contributing guidance, code of conduct, security policy, and templates in the conventional locations so the platform surfaces them.
3. Separate source, tests, docs, and tooling. Predictable top-level directories let both people and automation target the right paths (see github-actions-workflows).
4. Keep configuration together. Scattered configuration files are the most common root clutter, and grouping them where the tooling allows keeps the root legible.
5. Write the readme for the first ten minutes. What it is, how to run it, and where to go next, before any badge collection.
6. Document the layout when it is not obvious. A short map of directories saves every newcomer the same exploration.
7. Keep generated artefacts out of version control. Build output and dependencies belong in ignore rules, and committing them creates noise in every diff (see repository-hygiene).

Boundaries

Conventions differ by language and ecosystem, and consistency with the ecosystem beats a personally preferred layout. Monorepos need additional structure for boundaries and ownership (see monorepo-workspaces). Restructuring an established repository breaks links and muscle memory, so it needs justification.