From 6044e5e71bf30bbe99684c8c6b89fdb4b840930e Mon Sep 17 00:00:00 2001 From: Matt Harvey Date: Tue, 5 May 2026 19:23:48 -0400 Subject: [PATCH] crawl: ex0 bootstrap --- .copilot-track/crawl/README.md | 38 ++++++++++++++++++++++++++++++++ ai-track-docs/SYSTEM-OVERVIEW.md | 37 +++++++++++++++++++++++++++++++ ai-track-docs/architecture.mmd | 14 ++++++++++++ ai-track-docs/build-test.md | 33 +++++++++++++++++++++++++++ 4 files changed, 122 insertions(+) create mode 100644 .copilot-track/crawl/README.md create mode 100644 ai-track-docs/SYSTEM-OVERVIEW.md create mode 100644 ai-track-docs/architecture.mmd create mode 100644 ai-track-docs/build-test.md diff --git a/.copilot-track/crawl/README.md b/.copilot-track/crawl/README.md new file mode 100644 index 0000000..a474e78 --- /dev/null +++ b/.copilot-track/crawl/README.md @@ -0,0 +1,38 @@ +# Crawl Track — How This Works + +## Chain-PRs +Each exercise lives on its own branch, created off the **previous exercise's branch** (not main). This forms a chain: + +``` +main + └── crawl//ex0-bootstrap + └── crawl//ex1-repo-orientation + └── crawl//ex2-build-test-baseline + └── ... +``` + +Why chain? So each PR shows only the incremental diff for that exercise — reviewers and your future self can follow the progression clearly. + +## Evidence in PRs +Every PR must include: +- **Test output** — paste the result of running your test command +- **Rollback plan** — `revert ` or describe what to undo +- **Review focus** — one sentence on what the reviewer should look at + +If you can't run tests, document why and what manual check you did instead. + +## Prompt Usage Pattern +For each exercise: +1. Open Copilot Chat with the repo open in VS Code +2. Paste the exercise prompt from `crawl-walk-run.instructions.md` +3. Append the standard suffix (plan → files → diffs → tests → PR draft) +4. Review Copilot's plan before accepting any file writes +5. Commit only what the acceptance criteria require — nothing more + +## Key Files +| File | Purpose | +|------|---------| +| `ai-track-docs/SYSTEM-OVERVIEW.md` | Repo summary + chosen module | +| `ai-track-docs/build-test.md` | Exact build/test commands | +| `ai-track-docs/architecture.mmd` | Mermaid architecture diagram | +| `.copilot-track/crawl/README.md` | This file | diff --git a/ai-track-docs/SYSTEM-OVERVIEW.md b/ai-track-docs/SYSTEM-OVERVIEW.md new file mode 100644 index 0000000..26293d7 --- /dev/null +++ b/ai-track-docs/SYSTEM-OVERVIEW.md @@ -0,0 +1,37 @@ +# System Overview + +## Repo +**github/copilot-cli-for-beginners** — A structured course teaching GitHub Copilot CLI usage through a single Python book-collection app that evolves across chapters. + +## Languages & Runtimes +- **Python** (primary) — `samples/book-app-project/` +- **C#** — `samples/book-app-project-cs/` +- **JavaScript** — `samples/book-app-project-js/` +- **Markdown** — course content in `00-quick-start/` through `07-putting-it-together/` + +## Entry Points +| App | File | +|-----|------| +| Python book app | `samples/book-app-project/book_app.py` | +| Python books module | `samples/book-app-project/books.py` | +| Python utils | `samples/book-app-project/utils.py` | + +## Test Approach +- **Framework:** pytest +- **Test files:** `samples/book-app-project/tests/test_books.py` +- **Config:** `samples/book-app-project/pyproject.toml` + +## Key Paths +| Path | Purpose | +|------|---------| +| `samples/book-app-project/` | Primary Python sample app (used for most exercises) | +| `samples/book-app-buggy/` | Intentionally broken version for debugging exercises | +| `00-quick-start/` → `07-putting-it-together/` | Course chapter content | +| `AGENTS.md` | Copilot agent customization instructions | +| `.github/` | CI workflows | + +## Chosen Low-Risk Module +> _To be filled in during Ex 1 — Repo Orientation_ + +**Module:** TBD +**Justification:** TBD diff --git a/ai-track-docs/architecture.mmd b/ai-track-docs/architecture.mmd new file mode 100644 index 0000000..d22f279 --- /dev/null +++ b/ai-track-docs/architecture.mmd @@ -0,0 +1,14 @@ +graph TD + A[book_app.py
Entry point / CLI] --> B[books.py
Book CRUD logic] + A --> C[utils.py
Shared helpers] + B --> D[data.json
Persistent storage] + B --> E[tests/test_books.py
pytest suite] + C --> E + + subgraph samples/book-app-project + A + B + C + D + E + end diff --git a/ai-track-docs/build-test.md b/ai-track-docs/build-test.md new file mode 100644 index 0000000..bc8c313 --- /dev/null +++ b/ai-track-docs/build-test.md @@ -0,0 +1,33 @@ +# Build & Test Commands + +## Python book app (`samples/book-app-project/`) + +### Run the app +```bash +cd samples/book-app-project +python book_app.py +``` + +### Run tests +```bash +cd samples/book-app-project +python -m pytest tests/ -v +``` + +### Install dependencies (if needed) +```bash +pip install pytest +# or, using pyproject.toml: +pip install -e . +``` + +## C# book app (`samples/book-app-project-cs/`) +> _To be filled in during Ex 2 if this app is chosen_ + +## JavaScript book app (`samples/book-app-project-js/`) +> _To be filled in during Ex 2 if this app is chosen_ + +--- + +> Updated during: Ex 0 — Bootstrap +> Last verified: _fill in when you run commands_