Repo Hygiene

Repo Hygiene

Owner: Engineering Last reviewed: 2026-Q2

This page defines what should and should not live in the repository.

Commit Only Source And Intentional Artifacts

Commit:

  • Source code.
  • Tests.
  • Handwritten docs.
  • Required config/templates.
  • Intentional generated clients when they are part of the app contract.
  • Alembic migration files.

Do not commit:

  • node_modules.
  • Python virtual environments such as env, .venv, or venv.
  • Build outputs such as dist.
  • Test/lint/type caches such as .pytest_cache, .ruff_cache, .mypy_cache, .vite, .cache.
  • Python bytecode and __pycache__.
  • .DS_Store and other OS metadata.
  • Local .env files with real values.

Before Opening A PR

Run:

git status --short

Check that every changed file is intentional. Generated files should have a clear source command. Secrets and local artifacts should be removed before review.

Local Cleanup

  • Remove accidental OS files from the changed area before committing.
  • Keep dependency installs local and untracked.
  • If a local artifact repeatedly appears, update .gitignore in a dedicated cleanup PR.

Documentation Drift

  • Update handbook pages when repo structure, commands, deployment flow, or operational expectations change.
  • If CLAUDE.md and the handbook disagree, treat the handbook as the team-facing source of truth and update CLAUDE.md or add a reference.
Database OperationsSecurity