Skip to content

Contributing

Contributions should help developers reason about real systems, not collect trivia.

Content checklist

  • Technically accurate and written in original words.
  • Clear scope and learning objectives.
  • Realistic, readable, runnable examples where applicable.
  • Code executed or tested; never claim tests that were not run.
  • Edge cases, failure modes, and common misconceptions addressed.
  • Trade-offs and alternatives explained.
  • Version-specific behavior identified.
  • External claims linked to authoritative sources.
  • No unnecessary duplication.

Prefer standard-library examples unless a dependency is essential. Interview answers should demonstrate reasoning, state assumptions, and discuss trade-offs.

Naming and URL policy

  • Use a distinctive, natural, descriptive filename in lowercase with hyphens.
  • Aim for roughly 3–6 meaningful words and about 30–60 characters when that fits the topic. This is a guide, not a forced limit: clarity takes priority over mechanical shortening or adding SEO filler.
  • Avoid dates, generic filler, redundant category words, and unnecessary directory nesting.
  • Search existing pages and navigation before choosing a slug; every published URL must be unique.
  • Keep published URLs stable. If a URL must change, add an explicit permanent redirect and update every internal link in the same change.

Git and review workflow

  • Start from the latest main and create a clearly named feature branch for the coherent handbook update.
  • Do not commit or push routine handbook changes directly to main.
  • Group related documentation, navigation, roadmap, tests, and example changes into one pull request.
  • Run the strict MkDocs build and relevant example tests before opening the pull request.
  • Check GitHub Actions and the Vercel Preview. Fix failures on the same branch and re-run the checks.
  • Merge only when required CI, technical validation, and the preview are successful. Prefer squash merge.
  • Preserve the existing portfolio build, MkDocs/GitHub Pages setup, published URLs, and unrelated application files.