CodeVetter · Repo Unpack · Contributor handoff
krahets/hello-algo
This is a content monorepo, not an app — treat it as five parallel trees (root zh + en, zh-hant, ja, ru) over two artifact types (docs markdown, runnable code). Read mkdocs.yml, Dockerfile, and the contribution docs first. The prime directive is consistency: any code change belongs in codes/ AND all locale codes/ copies AND the inline tabs in the docs pages; any structural change (new chapter/language) touches nav, manifests, workflows, and Docker stages together. Validate with the language's own harness before submitting; correctness means 'runs and prints the same results as the Python/Java reference' per the PR template.
- Read these first: mkdocs.yml (nav + build layout), Dockerfile (how all five sites build), docs/chapter_appendix/contribution.md (contribution flow), en/CONTRIBUTING.md (translation standards), .github/pull_request_template.md (required checklists), and the workflow file for whichever language you touch.
- Code file conventions: every sample has a header comment ('File: <name> / Created Time: <date> / Author: <name> (<email>)') and ends with a driver section — '"""Driver Code""" + if __name__ == "__main__":' in Python, '/* Driver Code */ func TestXxx(t *testing.T)' in Go, fn main() in Rust.
- Language of comments matters: codes/ and zh-hant/codes/ use Chinese comments; en/codes/ uses English translations of the same comments — match the locale's language when editing, don't mix.
- When editing a sample, update in lockstep: the codes/<lang>/ file, the matching en/zh-hant/ja/ru copies, the === 'Lang' tab block in the corresponding docs/<chapter>/<page>.md, and any codes/pythontutor/ URL that embeds that function's source.
- Local validation per language: python → 'black codes/python && cd codes/python && python test_all.py'; go → 'go build ./... && go test ./...'; rust → add [[bin]] then 'cargo build'; typescript → 'npm run check'; javascript → 'deno run -A test_all.js'; c/cpp → cmake -B build && cmake --build && ctest.
- Local site builds need the staged layout: mkdocs.yml points docs_dir at build/docs and custom_dir at build/overrides, so 'mkdocs serve' alone fails — replicate the Dockerfile's COPY steps (mkdir -p build && cp -r docs build/docs && cp -r overrides build/overrides) or just 'docker-compose up -d'.
- Trap — registries must stay in sync when adding/removing files: Cargo.toml [[bin]] entries, chapter CMakeLists add_executable lines, and the mkdocs.yml nav tree all reference files by name; a renamed or deleted sample breaks builds three ways.
- Trap — docs/index.html and docs/index.md coexist at docs root: the .html is the real hand-crafted landing page (hero + starfield + reviewer grid) while index.md is a 3-line stub; edit the HTML file for homepage changes.
- Safe-edit boundary: single-page markdown text fixes are low-risk (path filters skip CI anyway); code edits are medium-risk (5-tree sync); structural changes (new chapter/language/locale) are high-touch — nav, manifests, workflows, Dockerfile stages, and all locale trees change together. (inferred)
- Samples must stay self-contained and side-effect-free: files import only stdlib plus the language's own modules/pkg/include utils, print their results to stdout, and must exit 0 — the harnesses treat any crash as failure and there is no mocking/stubbing infrastructure.
- Output parity is the review standard: the PR template requires code transpilation PRs to attach console output proving it matches the Python or Java reference implementation — reproduce that locally before proposing changes.