diff --git a/.copilot-track/crawl/README.md b/.copilot-track/crawl/README.md index 8adf81bad..aba3577fc 100644 --- a/.copilot-track/crawl/README.md +++ b/.copilot-track/crawl/README.md @@ -2,6 +2,8 @@ This directory stores evidence, prompt snippets, and notes gathered during the **Crawl** phase of the AI-track course. +> **Branch strategy and PR automation are defined below** — read the [Branch Strategy](#branch-strategy) and [Automatic PRs](#automatic-prs) sections before starting exercises. + --- ## What is the Crawl phase? @@ -16,18 +18,139 @@ The track is structured as **Crawl → Walk → Run**: --- +## Branch Strategy + +Each exercise lives on its own branch, chained from the previous one so diffs stay focused: + +``` +main + └─ exercise-0 (bootstrap scaffolding) + └─ exercise-1 + └─ exercise-2 + └─ exercise-3 + └─ … +``` + +**Rules:** +- `exercise-0` branches from `main`. +- Each subsequent exercise branches from the **previous** exercise branch — never from `main`. +- PR base is always the **previous exercise branch** (not `main`), so reviewers see only the delta for that exercise. +- Merge commits are fine; rebasing is fine — just keep the chain intact. + +### Creating a branch for exercise N + +```bash +# Replace N with the exercise number, e.g. 3 +PREV=exercise-$((N-1)) +git checkout "$PREV" +git pull origin "$PREV" # sync if remote exists +git checkout -b exercise-$N +``` + +--- + +## Chain-PRs + +Each lesson produces a **chain PR** — a small, focused pull request that: + +1. Targets the **previous exercise branch** as base (not `main`). +2. Contains **evidence** that the stated goal was met (tests, screenshots, logs). +3. Uses the PR title format: `GHCP — Crawl: ` (e.g. `GHCP — Crawl: Ex1 Repo orientation`). +4. Follows the PR description template below. + +### Why chain PRs? + +- Keeps history linear and bisectable. +- Each PR is independently reviewable without a giant context window. +- Evidence in the PR body makes AI assistance auditable. + +--- + +## Automatic PRs + +Yes — you can open a PR automatically at the end of each exercise using the [GitHub CLI (`gh`)](https://cli.github.com/): + +```bash +# Run this at the end of every exercise (replace variables as needed) +EX=1 +NAME="Repo orientation" +PREV_BRANCH="exercise-$((EX-1))" +CURR_BRANCH="exercise-$EX" + +git push -u origin "$CURR_BRANCH" + +gh pr create \ + --base "$PREV_BRANCH" \ + --head "$CURR_BRANCH" \ + --title "GHCP — Crawl: Ex${EX} ${NAME}" \ + --body-file ".copilot-track/crawl/pr-body-ex${EX}.md" +``` + +**Tip:** Write your PR body into `.copilot-track/crawl/pr-body-ex.md` first, then run the command above. The body file is the single source of truth — commit it alongside your changes. + +Install gh if needed: `brew install gh && gh auth login` + +--- + +## Evidence in PRs + +Every PR description must include an **Evidence** section with actual command output: + +```markdown +## Evidence +- Tests/logs/metrics: + ``` + dotnet test --filter "..." → X passed, 0 failed + ``` +- Screenshot or log (for UI/behaviour changes) +- Prompt log: `.copilot-track/crawl/lesson-.md` +``` + +--- + ## Prompt usage -Save the prompts you used with Copilot here: +Save the prompts you used with Copilot here so teammates can reproduce results: ``` .copilot-track/crawl/ - lesson-01.md ← prompts + notes for lesson 1 + README.md ← this file + lesson-01.md ← prompts + notes for exercise 1 lesson-02.md - ... + pr-body-ex1.md ← PR body for exercise 1 (used by gh pr create) + pr-body-ex2.md + … ``` -Each file should contain: +Each `lesson-NN.md` file should contain: 1. The **prompt** you sent to Copilot (verbatim or paraphrased). 2. A brief **summary** of what worked / didn't work. 3. Any **follow-up prompts** needed to reach the final answer. + +--- + +## PR Description Template + +**Title format:** `GHCP — Crawl: ` +*(e.g. `GHCP — Crawl: Ex1 Repo orientation`)* + +```markdown +## Summary +- What changed and why +- Files/paths touched + +## Evidence +- Tests/logs/metrics: + ``` + + ``` +- Prompt log: `.copilot-track/crawl/lesson-.md` + +## Risk & Rollback +- Risk: low / medium / high +- Rollback: revert OR toggle + +## Track +- Level: Crawl +- Exercise: Ex +``` diff --git a/.copilot-track/crawl/pr-body-ex1.md b/.copilot-track/crawl/pr-body-ex1.md new file mode 100644 index 000000000..9c6180bc2 --- /dev/null +++ b/.copilot-track/crawl/pr-body-ex1.md @@ -0,0 +1,21 @@ +## Summary +- Updated `ai-track-docs/SYSTEM-OVERVIEW.md` with a full repo summary: languages, entry points, test approach, directory map, three low-risk modules, and a justified module recommendation. +- Updated `.copilot-track/crawl/README.md` with the canonical PR template, chain-branch strategy, and `gh pr create` automation command. +- Files touched: `ai-track-docs/SYSTEM-OVERVIEW.md`, `.copilot-track/crawl/README.md`, `.copilot-track/crawl/pr-body-ex1.md` + +## Evidence +- Tests/logs/metrics: no application code changed; no test changes required. + ``` + # Structural smoke + test -f ai-track-docs/SYSTEM-OVERVIEW.md && echo OK # OK + test -f .copilot-track/crawl/README.md && echo OK # OK + ``` +- Prompt log: `.copilot-track/crawl/lesson-01.md` *(add after exercise)* + +## Risk & Rollback +- Risk: low (documentation only, no source or test files modified) +- Rollback: `git revert HEAD` or delete branch + +## Track +- Level: Crawl +- Exercise: Ex1 diff --git a/ai-track-docs/SYSTEM-OVERVIEW.md b/ai-track-docs/SYSTEM-OVERVIEW.md index fdceaf411..ede34d7ee 100644 --- a/ai-track-docs/SYSTEM-OVERVIEW.md +++ b/ai-track-docs/SYSTEM-OVERVIEW.md @@ -1,16 +1,66 @@ # System Overview -> **Status:** Placeholder — fill in during the Crawl phase. +> **Status:** Updated — Crawl Exercise 1 +> **Chosen low-risk module:** `Squidex.Domain.Apps.Core.Model` (see justification below) + +--- ## What is Squidex? -Squidex is an open-source headless CMS built on ASP.NET Core (backend) and Angular (frontend). +Squidex is an open-source **headless CMS** with full content-API, real-time events, and a plugin system. + +--- + +## Languages & runtimes + +| Layer | Language / Runtime | Key tooling | +|-------|--------------------|-------------| +| Backend API | C# / .NET (ASP.NET Core) | `dotnet`, xUnit, NSubstitute | +| Frontend SPA | TypeScript / Angular | Angular CLI, Vitest | +| Plugin SDK | TypeScript / Preact | Webpack (preact-cli) | +| End-to-end tests | TypeScript / Node | Playwright | +| Load tests | TypeScript / k6 | k6 binary | +| Diagrams / docs | Mermaid, Markdown | — | + +--- + +## Entry points + +| Entry point | Path | +|-------------|------| +| Backend host | `backend/src/Squidex/Program.cs` | +| Backend DI / middleware | `backend/src/Squidex/Startup.cs` | +| Frontend bootstrap | `frontend/src/main.ts` | +| Frontend Angular root | `frontend/src/app/` | +| Docker image | `Dockerfile` (root) | + +--- + +## Test approach + +| Suite | Location | Count / files | Runner | +|-------|----------|---------------|--------| +| Backend unit & integration | `backend/tests/` | 7 `.csproj` projects | `dotnet test` / xUnit | +| Frontend unit | `frontend/src/**/*.spec.ts` | ~140 spec files | Vitest | +| End-to-end | `tools/e2e/` | ~36 TypeScript files | Playwright | +| Load | `tools/k6/` | k6 scripts | k6 binary | -## Top-level directories +CI entry points are in `.github/workflows/` (check root for workflow files). + +--- + +## Top-level directory map | Directory | Description | |-----------|-------------| -| `backend/` | ASP.NET Core solution — domain, infrastructure, API | +| `backend/src/Squidex` | ASP.NET Core host — API controllers, middleware, startup | +| `backend/src/Squidex.Domain.Apps.Core.Model` | Pure domain model — value objects, aggregates, schemas | +| `backend/src/Squidex.Domain.Apps.Core.Operations` | Domain operations / processing logic | +| `backend/src/Squidex.Domain.Apps.Entities` | Entity read/write handlers, command bus | +| `backend/src/Squidex.Infrastructure` | Cross-cutting utilities — eventing, queries, tasks, logging | +| `backend/src/Squidex.Shared` | Shared constants — permission IDs, text resources (12 files) | +| `backend/src/Squidex.Data.MongoDb` | MongoDB data adapters | +| `backend/src/Squidex.Data.EntityFramework` | SQL / EF Core data adapters | | `frontend/` | Angular SPA | | `sdk/` | Preact-based plugin/widget SDK | | `tools/e2e/` | Playwright end-to-end tests | @@ -18,14 +68,37 @@ Squidex is an open-source headless CMS built on ASP.NET Core (backend) and Angul | `ai-track-docs/` | AI-track reference docs (this folder) | | `.copilot-track/` | Copilot-track helper prompts & crawl evidence | +--- + +## Three low-risk modules + +| # | Module | Why low-risk | +|---|--------|--------------| +| 1 | `Squidex.Domain.Apps.Core.Model` | Pure C# value objects / record types. No I/O, no DI, no HTTP. 112 test files provide tight safety net. Changes are confined to domain invariants. | +| 2 | `Squidex.Infrastructure` | Cross-cutting utilities (tasks, queries, timers). 96 test files. Broadly used but changes to leaf utilities are isolated. | +| 3 | `Squidex.Shared` | Tiny module (12 files): permission ID constants and `.resx` text resources. Zero runtime logic — almost impossible to break anything. | + +### ✅ Chosen module: `Squidex.Domain.Apps.Core.Model` + +**Justification:** +- **No I/O or external dependencies** — pure in-memory domain types; changes can never break database adapters, API routing, or authentication. +- **Rich test suite** — 112 test files in `Squidex.Domain.Apps.Core.Tests` give immediate red/green feedback. +- **Well-scoped** — sub-directories (`Apps`, `Schemas`, `Contents`, `Assets`, `Rules`, `Comments`, `Teams`) make it easy to pick a single concept to modify without touching others. +- **Reusable across exercises** — schema validation, field type models, and content value types appear in later Walk/Run exercises, so understanding this module pays forward. + +--- + ## Key external dependencies -- MongoDB (primary datastore) or Entity Framework (SQL alternative) -- ASP.NET Core Identity / OpenID Connect -- Angular CLI, Vitest (unit), Playwright (e2e) +- MongoDB (primary datastore) or Entity Framework / SQL (alternative) +- ASP.NET Core Identity / OpenID Connect (auth) +- Angular Material (UI components) +- Vitest, Playwright, k6 (testing) + +--- -## TODO — complete during Crawl +## TODO -- [ ] List major bounded contexts / domain aggregates -- [ ] Document auth flow -- [ ] Note any feature flags or environment variables required for local dev +- [ ] Document auth flow (OpenID Connect provider config) +- [ ] Identify environment variables required for `dotnet run` locally +- [ ] Confirm CI workflow file names in `.github/workflows/`