Tirsvad-Udemy-100-days-of-code/025-us-states-game
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add plan baseline: business case, stakeholders, project plan, four milestones, reviews

Browse Source 
Refs: plan accepted by S01 in chat (autonomous mode)
This commit is contained in:
Tirsvad
2026-10-13 15:40:07 +08:00
parent 79812cb44f
commit b113e6eacd
16 changed files with 1040 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/milestones/mil-001-baseline-setup.md
+72
View File
@@ -0,0 +1,72 @@
# MIL-001 Baseline and repository setup
## Metadata
| Key | Value |
| --- | --- |
| ID | MIL-001 |
| CrossReference | [BC-001] |
| Language | en |
| Domain | it |
## Version History
| Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- |
| 2026-10-13 | Accepted | Claude (AI) for S01 | AI as stand-in for S01 | Initial version; review RC-003: Go | pending |
---
## Purpose
Decide whether the repository is ready to build in: tooling, layout, assignment assets, continuous integration (CI) and the public repository surface exist before any game code.
## Deliverable
A repository with `src/`, `tests/`, `docs/`, `.gitignore`, `pyproject.toml`, `constants.py`, the assignment assets, a `Doxyfile`, a README skeleton, a CI workflow, and a description and topics set on the git host.
## Go / No-Go Criteria
| # | Criterion (objectively checkable) | Go | No-Go |
| --- | --- | --- | --- |
| 1 | `pip install -e ".[dev]"` and `pytest` run in a fresh `.venv` on Python 3.13 or newer (zero tests collected is acceptable) | Met | Not met |
| 2 | `.gitignore` ignores `.venv/`, `__pycache__/`, `.env` and `docs/build` | Met | Not met |
| 3 | `doxygen Doxyfile` runs without error | Met | Not met |
| 4 | The repository description and at least 5 topics are visible on the git host | Met | Not met |
| 5 | The CI workflow file exists and installs and runs pytest | Met | Not met |
## Dependencies
| Depends on | Reason |
| --- | --- |
| None | First milestone |
## Traceability
| Business Case objective / KPI / user story | Reference |
| --- | --- |
| Objective 4; Success criteria 3, 5, 6 | [BC-001] |
## Ownership
| Role | Stakeholder ID (SA) |
| --- | --- |
| Owner | S01 |
| Approving reviewer | S01 |
## Target Date
2026-10-13 - within the one-working-day duration constraint of [BC-001].
## Tasks
| # | Task | Summary | Needs its own Use Case/User Story? | Reference |
| --- | --- | --- | --- | --- |
| 1 | Set repository description and topics | Set a one-sentence description and topics (`python`, `turtle-graphics`, `quiz-game`, `udemy`, `100-days-of-code`, `us-states`) through the git host API. The token is read from `.env` by the shell only; it is never imported, tested, printed or committed. Serves S03. | No | |
| 2 | Add .gitignore, pyproject.toml and project layout | Python `.gitignore`; `pyproject.toml` with `requires-python = ">=3.13"` and a `dev` extra with pytest; `src/` package and `tests/` folder. Constants live in `constants.py`. Serves the Business Case constraints. | No | |
| 3 | Add assignment assets | Unpack `50_states.csv` and `blank_states_img.gif` from the course zip into the package data folder. They are course-provided inputs the game needs at run time. | No | |
| 4 | Add Doxyfile | Configuration so `doxygen Doxyfile` builds the source reference from `src/` into `docs/build/doxygen`, with Python Doxygen comments (`##` and `@param`) supported. | No | |
| 5 | Add README skeleton and venv instructions | Create `README.md` from the framework template with every required section, including how to create a local `.venv` and run `python -m pip install --upgrade pip` on Windows PowerShell, Linux Debian and macOS. Filled in with screenshots in MIL-004. | No | |
| 6 | Add continuous integration workflow | A Gitea Actions workflow that sets up Python 3.13, installs the project with the dev extra and runs pytest, so the README Continuous integration section has something to describe. | No | |
---
[BC-001]: ../business-case.md
docs/milestones/mil-002-game-core.md
+71
View File
@@ -0,0 +1,71 @@
# MIL-002 Game core logic
## Metadata
| Key | Value |
| --- | --- |
| ID | MIL-002 |
| CrossReference | [BC-001] |
| Language | en |
| Domain | it |
## Version History
| Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- |
| 2026-10-13 | Accepted | Claude (AI) for S01 | AI as stand-in for S01 | Initial version; review RC-004: Go | pending |
---
## Purpose
Decide whether the game rules work and are tested without a display: loading states, checking guesses, finding missing states and writing the learning file.
## Deliverable
A display-free module with the game logic and pytest tests, plus an Architecture Decision Record (ADR) for the data library choice.
## Go / No-Go Criteria
| # | Criterion (objectively checkable) | Go | No-Go |
| --- | --- | --- | --- |
| 1 | `pytest` passes with tests for load, guess matching, missing states and CSV export | Met | Not met |
| 2 | Guess matching is case-insensitive and ignores surrounding spaces (`ohio` matches `Ohio`) | Met | Not met |
| 3 | `states_to_learn.csv` lists exactly the 50 states minus those guessed, in one column `state` | Met | Not met |
| 4 | The logic imports no `turtle` module | Met | Not met |
| 5 | The ADR for the data library is `Accepted` | Met | Not met |
## Dependencies
| Depends on | Reason |
| --- | --- |
| MIL-001 | Layout, tooling and assets must exist |
## Traceability
| Business Case objective / KPI / user story | Reference |
| --- | --- |
| Objectives 1, 2, 3; Success criteria 1, 2, 6 | [BC-001] |
## Ownership
| Role | Stakeholder ID (SA) |
| --- | --- |
| Owner | S01 |
| Approving reviewer | S01 |
## Target Date
2026-10-13 - within the one-working-day duration constraint of [BC-001].
## Tasks
| # | Task | Summary | Needs its own Use Case/User Story? | Reference |
| --- | --- | --- | --- | --- |
| 1 | Record ADR: csv module versus pandas | Decide whether to read `50_states.csv` with the standard library or pandas. S03 wants no runtime dependencies, S02 follows a pandas lecture. Record the decision and its consequences as an ADR. | No | |
| 2 | Load states data | Read `50_states.csv` into a structure keyed by state name with `x` and `y`, using paths and column names from `constants.py`. | No | |
| 3 | Check a guess | Match a typed answer to a state case-insensitively and return its coordinates, so the UI can write the name at that place (lecture 2). | No | |
| 4 | Find missing states and write states_to_learn.csv | Compute `missing_states` from all states and `guessed_states` and save them as `states_to_learn.csv` (lecture 3). | No | |
| 5 | Add pytest tests for the game core | Tests for load, guess, missing states and CSV output using a temporary directory; they must run without a display. | No | |
---
[BC-001]: ../business-case.md
docs/milestones/mil-003-turtle-game.md
+73
View File
@@ -0,0 +1,73 @@
# MIL-003 Turtle game and entry point
## Metadata
| Key | Value |
| --- | --- |
| ID | MIL-003 |
| CrossReference | [BC-001] |
| Language | en |
| Domain | it |
## Version History
| Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- |
| 2026-10-13 | Accepted | Claude (AI) for S01 | AI as stand-in for S01 | Initial version; review RC-005: Go | pending |
---
## Purpose
Decide whether the playable game works end to end: map, input prompts, drawn names, counter in the title, `exit` and the learning file.
## Deliverable
A runnable `main.py` entry point that plays the full game with Turtle, built on the tested core, with the click-coordinate helper from lecture 1.
## Go / No-Go Criteria
| # | Criterion (objectively checkable) | Go | No-Go |
| --- | --- | --- | --- |
| 1 | `python main.py` starts and shows the blank map titled "U.S. States Game" | Met | Not met |
| 2 | A correct guess writes the state name at its coordinates and increments the counter in the title | Met | Not met |
| 3 | A wrong guess re-opens the prompt without a crash | Met | Not met |
| 4 | Typing `exit` ends the game and writes `states_to_learn.csv` | Met | Not met |
| 5 | Guessing all 50 states ends the game | Met | Not met |
| 6 | The Turtle layer has a pytest test using a fake screen (no display needed) | Met | Not met |
## Dependencies
| Depends on | Reason |
| --- | --- |
| MIL-002 | The UI is built on the tested game core |
## Traceability
| Business Case objective / KPI / user story | Reference |
| --- | --- |
| Objectives 1, 2; Success criterion 1 | [BC-001] |
## Ownership
| Role | Stakeholder ID (SA) |
| --- | --- |
| Owner | S01 |
| Approving reviewer | S01 |
## Target Date
2026-10-13 - within the one-working-day duration constraint of [BC-001].
## Tasks
| # | Task | Summary | Needs its own Use Case/User Story? | Reference |
| --- | --- | --- | --- | --- |
| 1 | Set up screen, title and map image | Create the `screen`, set the title and register `blank_states_img.gif` as a shape (lecture 1), kept in a function with the assignment name. | No | |
| 2 | Add mouse click coordinate helper | `get_mouse_click_coor(x, y)` prints click coordinates and the screen stays open with `mainloop`, as in lecture 1. | No | |
| 3 | Implement the guess loop | While fewer than 50 states are guessed, prompt with `textinput`, title-case the answer, write the state at its coordinates and update the counter (lecture 2); `exit` breaks the loop (lecture 3). | No | |
| 4 | Add the entry point | `main.py` wires screen, loop and the learning-file export so `python main.py` runs the game after setup. | No | |
| 5 | Add UI test with a fake screen | Inject a fake screen and prompt into the loop to verify the flow without a display. | No | |
| 6 | Run the game manually | Run the real game once and note the result in the milestone review. | No | |
---
[BC-001]: ../business-case.md
docs/milestones/mil-004-docs-release.md
+72
View File
@@ -0,0 +1,72 @@
# MIL-004 Documentation, screenshots and wiki
## Metadata
| Key | Value |
| --- | --- |
| ID | MIL-004 |
| CrossReference | [BC-001] |
| Language | en |
| Domain | it |
## Version History
| Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- |
| 2026-10-13 | Accepted | Claude (AI) for S01 | AI as stand-in for S01 | Initial version; review RC-006: Go | pending |
---
## Purpose
Decide whether the repository is publishable for S02 and S03: README, source reference, screenshots and a three-language wiki.
## Deliverable
Completed README with screenshots, Doxygen comments verified and buildable, wiki pages in English, Danish and Bahasa Malaysia with screenshots, and a verified fresh-clone run.
## Go / No-Go Criteria
| # | Criterion (objectively checkable) | Go | No-Go |
| --- | --- | --- | --- |
| 1 | `framework/scripts/check-readme.sh` passes | Met | Not met |
| 2 | `doxygen Doxyfile` builds without warnings about undocumented public functions | Met | Not met |
| 3 | The wiki has `Home`, `Install` and `Description` pages in `en`, `da` and `ms` and a `_Sidebar.md` | Met | Not met |
| 4 | README and wiki embed at least 2 screenshots of the running game | Met | Not met |
| 5 | A fresh clone follows the README and the game and tests run | Met | Not met |
## Dependencies
| Depends on | Reason |
| --- | --- |
| MIL-003 | There must be a running game to screenshot |
## Traceability
| Business Case objective / KPI / user story | Reference |
| --- | --- |
| Objective 4; Success criteria 3, 4, 5 | [BC-001] |
## Ownership
| Role | Stakeholder ID (SA) |
| --- | --- |
| Owner | S01 |
| Approving reviewer | S01 |
## Target Date
2026-10-13 - within the one-working-day duration constraint of [BC-001].
## Tasks
| # | Task | Summary | Needs its own Use Case/User Story? | Reference |
| --- | --- | --- | --- | --- |
| 1 | Capture screenshots of the running game | Take screenshots of the start screen and a game in progress from the real game, stored under `docs/images/`, used by README and wiki. Serves S02 and S03. | No | |
| 2 | Complete README | Fill every template section (requirements, set up for PowerShell, Debian and macOS, run, tests, continuous integration, source documentation, layout, license) and embed the screenshots. | No | |
| 3 | Review Doxygen comments and build | Verify every public function and constant has a Doxygen comment, run `doxygen Doxyfile`, and document the command in the README. | No | |
| 4 | Write the wiki in English, Danish and Bahasa Malaysia | Pages `Home`, `Install`, `Description` and `_Sidebar.md` under `wiki/` in the same layout as the TirSystem github-action wiki, each with `-da` and `-ms` variants and screenshots. | No | |
| 5 | Publish the wiki to the git host | Push the `wiki/` pages to the repository wiki on the git host. | No | |
| 6 | Verify from a fresh clone | Clone to a clean folder, follow the README, run the game and tests, and record the result. | No | |
---
[BC-001]: ../business-case.md