Skip to content

Project structure

A consistent project layout makes it easier to onboard new contributors, keep expectations clear, and automate tooling. The items below describe common documentation and legal files that appear at the repository root, along with the reasons they exist. It focuses on placement and purpose rather than file contents.

Root documentation files

README

  • Introduces what the project is and who it is for.
  • Provides the fastest path to setup or usage.
  • Links to deeper docs without duplicating them.

CONTRIBUTING

  • Explains how to propose changes and where to start.
  • Lists expectations for branches, commits, and review flow.
  • Reduces back-and-forth on contribution norms.

CODE_OF_CONDUCT

  • Sets expectations for community behavior.
  • Defines reporting paths for incidents.
  • Creates a safer, more inclusive contributor experience.

CHANGELOG

  • Summarizes notable changes across releases.
  • Helps users evaluate upgrade impact quickly.
  • Aligns release notes with version history.

SECURITY

  • Describes how to report security issues.
  • Communicates response expectations for sensitive reports.
  • Keeps disclosure channels consistent and private.

SUPPORT

  • Directs users to preferred support channels.
  • Prevents issue trackers from becoming help desks.
  • Clarifies what help is and is not available.

GOVERNANCE

  • Documents decision-making structures and roles.
  • Clarifies ownership for long-term maintenance.
  • Helps contributors understand how direction is set.

LICENSE

  • Grants legal permission to use and distribute the project.
  • Makes reuse terms explicit for users and downstream projects.
  • Enables package registries to show license metadata.

NOTICE

  • Captures required attributions for included dependencies.
  • Keeps legal obligations visible alongside the license.
  • Simplifies compliance for downstream users.

PATENTS

  • Clarifies patent grants or non-assert commitments.
  • Reduces uncertainty for commercial adopters.
  • Complements open-source license terms when needed.

Docs directory patterns

docs/

  • Central place for extended guides and tutorials.
  • Keeps the root directory focused and scannable.
  • Lets tooling build documentation without guessing locations.

docs/architecture/

  • Stores diagrams and rationale about key design choices.
  • Prevents architectural context from being buried in issues.
  • Helps reviewers evaluate changes against decisions.

docs/decisions/

  • Tracks decision records that explain why choices were made.
  • Preserves historical context for future maintainers.
  • Keeps design rationale discoverable and searchable.

docs/runbooks/

  • Holds operational guides for on-call or support workflows.
  • Standardizes response during incidents.
  • Reduces time-to-recovery by clarifying steps.

Tips for usage

  • Place these files at the repository root for discoverability.
  • Keep short summaries in the root docs, and link to deeper docs.
  • Align file names with platform expectations (for example, GitHub).