Document-as-Code Lab

Source file

Repository Guidance

Sources and Scope

  • Use the project source map to locate authoritative information and the tutorial specification register for design intent and dated decisions. Follow links relevant to the task; these files do not grant permissions or imply automatic context loading.

  • Read CONTRIBUTING.md before editing tutorial content. Write project documentation in English.

  • Before rewriting prose, read the editorial rules in CONTRIBUTING.md, the shared vocabulary, and the approved narrative direction in the tutorial specification. Present representative before/after passages for owner approval before a major site-wide style change; preserve chapter objectives, source identifiers, and meaningful distinctions.

  • Keep docs/ as the chapter source of truth. Astro in site/ reads these files; do not duplicate or move them into the site.

  • Preserve stable chapter IDs. Filename prefixes and chapter_number determine reading order.

  • Keep existing user changes. Commit, push, or change GitHub settings only when requested.

For a capability, publication, or workflow change, inspect the following files and update those affected. Do not edit every file mechanically.

  • README.md: current status, available outputs, links, next milestone, and licensing.
  • site/README.md: reproducible local commands, deployment, base path, and widget behavior.
  • docs/03-project-growth.md: the history and traceability chapter with a dashboard link. data/features.json: capability milestones and verification evidence. Mark complete only after its criterion is verified.
  • docs/10-publishing.md and docs/11-beyond-github.md: actual workflow behavior, hosted status, lab architecture, and remaining output pipelines.
  • ROADMAP.md: remaining work and decisions; do not leave completed choices described as undecided.
  • CONTRIBUTING.md and LICENSE.md: conventions, license scope, and attribution when relevant.
  • Supporting assets, tables, captions, links, and source lists when their inputs change.

Distinguish chapter draft status, approval, capability completion, and successful deployment. A passing build does not establish all four.

Website and History

  • Preserve the GitHub Pages base path /document-as-code-lab/ in navigation, Markdown links, images, and scripts. Check both local and hosted paths.
  • The chapter widget uses front matter and chapter-specific Git history collected at build time. Preserve full-history checkout in workflows; it is not a live API feed.
  • Fixed charts under assets/figures/ are historical teaching snapshots. Do not silently refresh their values or source revisions.
  • Growth workflow artifacts do not automatically update chapter charts. Label working-tree previews separately from committed measurements.
  • The Project Control Center’s growth widget uses a separate JSON report regenerated by site/’s predev and prebuild hooks. Keep its measurement rules shared with the Python script, preserve Python setup in the website workflows, and restart the local server after new commits to refresh the report.
  • Keep site/dist/, site/node_modules/, .astro/, and working reports under build/ out of commits.
  • When linking a new supporting source, check its material route and the explicit source-file selection in site/src/lib/repository.ts.

Verification and Publication

  • From site/, run npm run check and npm run build. Use ASTRO_TELEMETRY_DISABLED=1 when sandboxed execution requires it.
  • Run .venv/bin/python -m unittest discover -s tests from the root when changing measurement or processing behavior.
  • Run node scripts/test-budget.mjs from site/ when validating the website. For the optional PDF proof, follow publishing/pdf/README.md, run its focused tests, and inspect rendered pages. Record whether Mermaid CLI or a prepared SVG was used; do not claim the full PDF pipeline is verified from the prepared-SVG path alone.
  • For milestone changes, regenerate scripts/measure_growth.py reports with the appropriate Python environment; use --include-working-tree before committing.
  • Check git diff --check, changed-file scope, internal links, and representative images and diagrams. Verify one title and one widget per chapter when changing their rendering.
  • If Markdown rendering configuration changes but old HTML persists locally, use npm exec astro sync -- --force for development. npm run build already uses astro build --force so cached Markdown does not hide renderer changes in production.
  • Before an authorized push, synchronize with the remote without discarding changes. After publication, verify the deployment run and affected live pages. Report the exact commit and distinguish local checks from hosted verification.
  • Search affected documentation for stale claims such as “deployment not configured”, “pending publication”, or “no license selected”. Preserve genuinely historical explanations.