Repository Structure

A typical layout

my-project/
├── README.md            what it is, and how to build, run and test it
├── LICENSE              the terms of use
├── .gitignore           files Git should not track
├── src/                 application source code
├── tests/               automated tests
├── docs/                longer documentation, decisions, diagrams
├── scripts/             helper scripts for setup, build and deployment
├── .github/workflows/   CI pipelines (other hosts use their own files)
└── package.json         build and dependency manifest (pom.xml, *.sln, pyproject.toml, ...)

The details differ between languages and frameworks. Follow the conventions of the framework you use rather than inventing your own.

Files worth knowing

• README: the purpose of the project, prerequisites, how to set up, run and test, and how to contribute. This is the first thing to read.
• LICENSE: whether and how the code may be used.
• CONTRIBUTING and CHANGELOG: how to contribute, and what changed between releases.
• CODEOWNERS: who must review changes to which parts.
• Lock files (for example package-lock.json): pin exact dependency versions. Commit them for applications.
• CI configuration: shows exactly how the project is built and tested.

One repository or many

A monorepo keeps many projects in one repository, which makes cross-cutting changes easy. Separate repositories give each project its own history, access control and release cycle. Neither is better in general. Your team has probably already chosen.

Finding your way in a new repository

1. Read the README.
2. Look at the top-level folders and the manifest file.
3. Read the CI configuration to see how it is built and tested.
4. Find the entry point and follow one feature from there.

Try it

Clone a well-known open source project and answer: what does it do, how do you build it, where are the tests, and who owns what?