Tirsvad-Udemy-100-days-of-code/024-snake
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Plan the Day 24 snake game: business case, stakeholders, dictionary, plan and five milestones

Browse Source
This commit is contained in:
Tirsvad
2026-10-13 14:11:42 +08:00
parent a73e941fb6
commit e004c34565
20 changed files with 1501 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/milestones/mil-001-project-foundation.md
+92
View File
@@ -0,0 +1,92 @@
# MIL-001: Project foundation
## 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 | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version, reviewed in RC-004 (Go) | pending |
---
## Purpose
This gate decides whether the repository has the files that carry no game logic yet: configuration, ignore rules, constants, README, source documentation settings, the continuous integration workflow, and the repository description and topics. The work is delivered on the branch `mil-001-project-foundation` and one pull request.
## Deliverable
`pyproject.toml`, the Python `.gitignore`, the package `src/snake_game/` with `__init__.py` and `constants.py`, `tests/test_constants.py`, `README.md` following the Product Owner's template, `Doxyfile`, and `.gitea/workflows/ci.yml`. The repository description and topics on the git host are set. Each adopted file is copied from [021-snake-game] and changed only where the identity of this repository requires it; the pull request lists every difference from the base.
Proposed repository description and topics, for S01 to confirm by accepting the plan:
- Description: "Snake game in Python with turtle graphics, day 24 of Udemy's 100 Days of Code bootcamp: continuous play and a high score kept in a file between games. pytest tests, Doxygen docs, no runtime dependencies."
- Topics: `100-days-of-code`, `doxygen`, `education`, `file-handling`, `game`, `high-score`, `oop`, `pytest`, `python`, `python-bootcamp`, `snake-game`, `turtle-graphics`, `udemy`.
## Go / No-Go Criteria
| # | Criterion (objectively checkable) | Go | No-Go |
| --- | --- | --- | --- |
| 1 | In a fresh clone, `python -m venv .venv`, `python -m pip install --upgrade pip` and `python -m pip install -e ".[dev]"` succeed in Windows PowerShell | All three commands exit 0 | Any command fails |
| 2 | `pytest` runs | Exit code 0, at least one test of `constants.py`, no window opened | Failing test, or no test of `constants.py` |
| 3 | `pyproject.toml` states the Python version and the dependencies | `requires-python = ">=3.13"`, `dependencies = []`, a `dev` extra with pytest, and a repository URL that names this repository | Any of the four is missing or different |
| 4 | The `.gitignore` protects local files | `git check-ignore .venv .env __pycache__ data.txt` lists all four | One of them is not ignored |
| 5 | `constants.py` holds the values of the base, with Doxygen comments | Every value of the `constants.py` of [021-snake-game] is a constant with a Doxygen comment | A value is missing or has no Doxygen comment |
| 6 | `doxygen Doxyfile` builds the source documentation | Ends with 0 warnings and writes HTML for `src/` | Any warning, or no output |
| 7 | The README follows the Product Owner's template | Every section title of the template in the given order (Requirements, Set up with Windows powershell, Linux debian and MacOS, Run, Run the tests, Continuous integration, Build the source documentation, Project layout, License), with commands for the three systems | A heading is missing or out of order, or a section has no commands |
| 8 | The CI workflow exists | `.gitea/workflows/ci.yml` installs `.[dev]` and runs `pytest`, `ruff` and `mypy` on Python 3.13, and nothing under `.github/workflows` exists | No workflow, or it does not run the tests, or a file exists under `.github/workflows` |
| 9 | The repository page is complete | Description is non-empty and there are at least 5 topics on the git host | Description empty or fewer than 5 topics |
| 10 | The adopted files are traceable to the base | The pull request lists every difference between each adopted file and the base, or says that there is none | A difference that the list does not name |
| 11 | The code is reviewed | `RC-*` against `QC-PY-001` has the verdict `Go` | Verdict `No-Go` or `Go-with-conditions` |
| 12 | No secret is in the change | `.env` is not tracked and no token appears in any changed file | A token is found in the diff |
## Dependencies
| Depends on | Reason |
| --- | --- |
| [PP-001] accepted | The plan schedules this gateway; the plan-first gate needs it before any code |
| This milestone accepted with a `Go` review | The plan-first gate allows no file under `src/` or `tests/` before that |
## Traceability
| Business Case objective / KPI / user story | Reference |
| --- | --- |
| Objective 8: reproducible environment, no runtime dependencies | [BC-001], criteria 7 and 9 in Success Criteria |
| Objective 9: tests without a display | [BC-001], criterion 6 in Success Criteria |
| Objective 10: Doxygen and README | [BC-001], criteria 7 and 8 in Success Criteria |
| Objective 12: repository page | [BC-001], criterion 12 in Success Criteria |
| Objective 11: traceable steps; the base is adopted without hidden change | [BC-001], criteria 11 and 13 in Success Criteria |
## Ownership
| Role | Stakeholder ID (SA) |
| --- | --- |
| Owner | S01 |
| Approving reviewer | S01 |
## Target Date
2026-10-15 — first of five gateways, inside the plan of [PP-001] that ends 2026-10-25.
## Tasks
| # | Task | Summary | Needs its own Use Case/User Story? | Reference |
| --- | --- | --- | --- | --- |
| 1 | Add pyproject.toml for the Day 24 repository | Adopt `pyproject.toml` from the base for the `snake-game` project: `requires-python = ">=3.13"`, an empty `dependencies` list, a `dev` extra with pytest, ruff and mypy, the `src` layout for the package `snake_game`, the pytest settings, and a description and repository URL that name this repository and day 24. Serves objective 8: a reproducible environment without runtime dependencies. | No | |
| 2 | Add the Python .gitignore for the Day 24 repository | Adopt the Python `.gitignore` from the base: bytecode, `.venv/`, build and packaging output, pytest, ruff, mypy and Doxygen caches. It also ignores `.env`, so the personal tokens can never be committed, and `data.txt`, the player's own high score file. | No | |
| 3 | Adopt constants.py and its test | Copy `src/snake_game/__init__.py`, `src/snake_game/constants.py` and `tests/test_constants.py` from the base. Every value is an `UPPER_SNAKE` constant with a Doxygen comment. The day-24 constants are added in MIL-003 and MIL-004. | No | |
| 4 | Add the README for the Day 24 repository | Adopt `README.md` from the base and rewrite its identity for this repository (name, day 24, clone address). Keep the Product Owner's template. Document creating a local `.venv`, `python -m pip install --upgrade pip` and `python -m pip install -e ".[dev]"`; name `python3-tk` and Debian 13 for Linux. The Run section is finished in MIL-005. Serves S02 and S03. | No | |
| 5 | Add the Doxyfile for the Day 24 repository | Adopt the `Doxyfile` from the base: it reads `src/`, writes to `build/doxygen`, extracts documentation for Python and treats warnings as failures; the project brief names day 24. | No | |
| 6 | Add the continuous integration workflow | Adopt `.gitea/workflows/ci.yml` from the base: check out, set up Python 3.13, upgrade `pip`, install `.[dev]`, run `pytest`, `ruff` and `mypy`. The file stays in `.gitea/workflows`, not `.github/workflows`, so the push mirror to GitHub is not blocked. | No | |
| 7 | Set the repository description and topics | Set the description and at least 5 topics of this repository on the git host with the Gitea application programming interface (API), using `GITEA_TOKEN` from the personal `.env` file; the file is only read by the command, never imported, tested or tracked. Use the proposed text of the Deliverable section. Serves S03 and objective 12. | No | |
---
[BC-001]: ../business-case.md
[PP-001]: ../project-plan.md
[021-snake-game]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/021-snake-game
docs/milestones/mil-002-adopt-the-game.md
+86
View File
@@ -0,0 +1,86 @@
# MIL-002: Adopt the game
## 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 | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version, reviewed in RC-005 (Go) | pending |
---
## Purpose
This gate decides whether the finished game of the base ([021-snake-game], `main`) runs in this repository: the snake, the food, the scoreboard, the main flow and all their tests are here, they pass, and the game can be played. It changes no behaviour; the day-24 changes start in [MIL-003]. The work is delivered on the branch `mil-002-adopt-the-game` and one pull request.
## Deliverable
`src/snake_game/snake.py`, `food.py`, `scoreboard.py`, `main.py` and `__main__.py`, and the tests `tests/fakes.py`, `test_snake.py`, `test_food.py`, `test_scoreboard.py` and `test_main.py`. Running `python -m snake_game` plays the game of day 21. The files are copied from the base and changed only where the identity of this repository requires it; the pull request lists every difference from the base.
## Go / No-Go Criteria
| # | Criterion (objectively checkable) | Go | No-Go |
| --- | --- | --- | --- |
| 1 | The adopted files match the base | The pull request lists every difference between each adopted file and the base, or says that there is none | A difference that the list does not name |
| 2 | All tests pass without a display | `pytest` exits 0; no test opens a window; every test of the base is present | A failing test, or a test of the base is missing |
| 3 | Tests, lint, format and types are clean | `pytest`, `python -m ruff check src tests`, `python -m ruff format --check src tests` and `python -m mypy` exit 0, as in continuous integration (CI); no test opens a window | Any of them fails |
| 4 | `doxygen Doxyfile` builds | 0 warnings | Any warning |
| 5 | The game can be played | S01 runs `python -m snake_game` in Windows PowerShell: the window opens, the snake moves and turns, food is shown, the snake eats and grows, the score rises, and the game ends at the wall and at the tail | The game does not start, or one of those things does not happen |
| 6 | Closing the window ends quietly | Closing the window during play, and after game over, ends the program with exit code 0 and no traceback | A traceback |
| 7 | Importing the main flow needs no display | Importing `snake_game.main` loads neither `turtle` nor `tkinter` | Either module is loaded by the import |
| 8 | Constants are in one place | No module other than `constants.py` defines a value of the lectures | A value is a literal in another module |
| 9 | The README matches the adopted game | The Run section and the Project layout of `README.md` describe the files and the command of this milestone | A sentence that is out of date, or a file or command that the README does not name |
| 10 | The code is reviewed | `RC-*` against `QC-PY-001` has the verdict `Go` | Verdict `No-Go` or `Go-with-conditions` |
| 11 | No secret is in the change | `.env` is not tracked and no token appears in any changed file | A token is found in the diff |
## Dependencies
| Depends on | Reason |
| --- | --- |
| [MIL-001] accepted and merged | The package, `constants.py`, the test set-up, the Doxyfile and the CI workflow exist there |
## Traceability
| Business Case objective / KPI / user story | Reference |
| --- | --- |
| Objective 1: the day-21 behaviour is kept | [BC-001], criterion 1 in Success Criteria |
| Objective 7: the assignment's names | [BC-001], criterion 10 in Success Criteria |
| Objective 9: tests without a display | [BC-001], criterion 6 in Success Criteria |
| Objective 11: the base is adopted without hidden change | [BC-001], criteria 11 and 13 in Success Criteria |
## Ownership
| Role | Stakeholder ID (SA) |
| --- | --- |
| Owner | S01 |
| Approving reviewer | S01 |
## Target Date
2026-10-17 — second of five gateways.
## Tasks
| # | Task | Summary | Needs its own Use Case/User Story? | Reference |
| --- | --- | --- | --- | --- |
| 1 | Adopt the test fakes | Copy `tests/fakes.py` from the base: the fake segment, the fake screen and the fake `Turtle` base class that record their calls, so that every test runs without a display. The fake `turtle` module is installed before `food` and `scoreboard` are imported. | No | |
| 2 | Adopt the Snake class and its tests | Copy `src/snake_game/snake.py` and `tests/test_snake.py` from the base: `create_snake`, `add_segment`, `extend`, `move`, `hits_wall`, `hits_tail`, `up`, `down`, `left`, `right`, the `segments` list and the `head`. | No | |
| 3 | Adopt the Food class and its tests | Copy `src/snake_game/food.py` and `tests/test_food.py` from the base: `class Food(Turtle)` with `refresh`, whose random place comes from one function that the tests replace. | No | |
| 4 | Adopt the Scoreboard class and its tests | Copy `src/snake_game/scoreboard.py` and `tests/test_scoreboard.py` from the base: `class Scoreboard(Turtle)` with `update_scoreboard`, `increase_score` and `game_over`. `game_over` is replaced in MIL-003. | No | |
| 5 | Adopt the main flow and the entry point | Copy `src/snake_game/main.py`, `src/snake_game/__main__.py` and `tests/test_main.py` from the base: the screen set-up, the key bindings, the animation loop with `game_is_on`, the eating check, the game-over check, the wait for a click and the quiet exit when the window is closed. | No | |
| 6 | Describe the adopted game in the README | Update the Run section and the Project layout of `README.md` so that they match the files and the command of this milestone (`python -m snake_game`, the modules of `src/snake_game/`, the tests). Serves S02 and S03. | No | |
| 7 | Verify the adopted game end to end | Run `pytest`, `ruff check`, `ruff format --check`, `mypy` and `doxygen Doxyfile` in a fresh `.venv`, run `python -m snake_game` until the game is over, close the window during play, and record the results and the list of differences from the base in the pull request. | No | |
---
[BC-001]: ../business-case.md
[PP-001]: ../project-plan.md
[MIL-001]: ./mil-001-project-foundation.md
[MIL-003]: ./mil-003-continuous-play-and-high-score.md
[021-snake-game]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/021-snake-game
docs/milestones/mil-003-continuous-play-and-high-score.md
+87
View File
@@ -0,0 +1,87 @@
# MIL-003: Continuous play and high score
## 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 | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version, reviewed in RC-006 (Go) | pending |
---
## Purpose
This gate decides whether the game follows the day-24 lectures on the high score and on continuous play: the scoreboard has a `high_score`, `reset` replaces `game_over`, a collision resets the snake and the score and the game goes on, and the old snake leaves the screen. The high score lives in memory only; the lecture itself shows that it is lost when the game is started again, and [MIL-004] stores it. The work is delivered on the branch `mil-003-continuous-play-and-high-score` and one pull request.
## Deliverable
Changed `src/snake_game/scoreboard.py`, `snake.py`, `main.py` and `constants.py`, with changed and added tests. `Scoreboard.game_over` and its test are removed; `Scoreboard.reset` and `Snake.reset` are added.
## Go / No-Go Criteria
| # | Criterion (objectively checkable) | Go | No-Go |
| --- | --- | --- | --- |
| 1 | The scoreboard shows both scores | The text is `Score: <score> High Score: <high_score>` and starts as `Score: 0 High Score: 0`; the label texts are constants; the old text is cleared before every write | A different text, a literal label outside `constants.py`, or text that is written over the old one |
| 2 | `Scoreboard.reset` follows the lecture | When `score > high_score`, `high_score` becomes the score; then the score is 0 and the scoreboard is written again; a lower or equal score leaves `high_score` unchanged | Any of the three cases behaves differently |
| 3 | `Snake.reset` clears the old snake | Every old segment is sent to a place off the screen (a constant), `segments` is emptied, the snake is created again at the three starting positions and `head` is the first new segment | An old segment stays on the screen, or `head` still refers to an old segment |
| 4 | A collision no longer ends the game | At the wall and at the tail, `scoreboard.reset()` and `snake.reset()` are called and the loop goes on; `game_over`, `GAME_OVER_TEXT` and the wait for a click are gone | The game stops, or a name of the removed game over remains |
| 5 | The snake is playable after a reset | After a reset the snake moves right from the starting positions, a reversal is still ignored, and the food keeps its place | The snake does not move, or turns back onto itself |
| 6 | The day-24 values are constants | The off-screen place and the label texts used by `reset` and the scoreboard are constants with Doxygen comments | A literal in another module |
| 7 | The day-21 tests still hold | Every test of [MIL-002] passes, or is changed on purpose and the change is named in the pull request | A test is deleted without being named |
| 8 | Tests, lint, format and types are clean | `pytest`, `python -m ruff check src tests`, `python -m ruff format --check src tests` and `python -m mypy` exit 0, as in continuous integration (CI); no test opens a window | Any of them fails |
| 9 | `doxygen Doxyfile` builds | 0 warnings | Any warning |
| 10 | The game can be played | S01 plays in Windows PowerShell: hits the wall and the tail twice, sees the score go back to 0, the high score keep the best, and the old snake disappear | Any of those does not happen |
| 11 | The code is reviewed | `RC-*` against `QC-PY-001` has the verdict `Go` | Verdict `No-Go` or `Go-with-conditions` |
| 12 | No secret is in the change | `.env` is not tracked and no token appears in any changed file | A token is found in the diff |
## Dependencies
| Depends on | Reason |
| --- | --- |
| [MIL-002] accepted and merged | The classes and the main flow that this milestone changes exist there |
## Traceability
| Business Case objective / KPI / user story | Reference |
| --- | --- |
| Objective 2: the high score and the scoreboard text | [BC-001], criterion 2 in Success Criteria |
| Objective 3: continuous play and `reset` | [BC-001], criterion 3 in Success Criteria |
| Objective 4: `Snake.reset` | [BC-001], criterion 3 in Success Criteria |
| Objective 7: the assignment's names | [BC-001], criterion 10 in Success Criteria |
## Ownership
| Role | Stakeholder ID (SA) |
| --- | --- |
| Owner | S01 |
| Approving reviewer | S01 |
## Target Date
2026-10-19 — third of five gateways.
## Tasks
| # | Task | Summary | Needs its own Use Case/User Story? | Reference |
| --- | --- | --- | --- | --- |
| 1 | Add the high score constants | Add to `constants.py`, with Doxygen comments: the label of the high score text, the place off the screen where an old segment is sent, and any other value the next tasks need. Add the matching test of `test_constants.py`. | No | |
| 2 | Add the high_score attribute and the scoreboard text | `Scoreboard.__init__` sets `self.high_score` to 0 next to `self.score`; `update_scoreboard` clears the old text and writes `Score: <score> High Score: <high_score>`; tests with the fake turtle check the text and the clearing. | No | |
| 3 | Replace game_over with reset in the Scoreboard | Remove `Scoreboard.game_over` and its test. Add `Scoreboard.reset`: when the score is higher than `high_score`, the high score becomes the score; the score becomes 0; `update_scoreboard` is called. Tests: higher, equal and lower score. | No | |
| 4 | Add Snake.reset | Add `Snake.reset`: send every segment of `segments` to the off-screen place, empty the list, call `create_snake` again and set `head` to `segments[0]`. Tests with fake segments check that no old segment remains and that the starting positions are used. | No | |
| 5 | Play on after a collision in the main flow | In `main.py`, a hit of the wall or of the tail calls `scoreboard.reset()` and `snake.reset()` and the loop goes on; the end-of-game check, the game-over text and `exitonclick` are removed; closing the window still ends quietly. Update `tests/test_main.py`. | No | |
| 6 | Update the README for continuous play | Describe in the Run section the two scores on the scoreboard and what a collision does now, and remove the sentences about game over. Serves S02 and S03. | No | |
| 7 | Verify continuous play end to end | Run `pytest`, `ruff check`, `ruff format --check`, `mypy` and `doxygen Doxyfile` in a fresh `.venv`, play with several collisions and close the window, and record the results and the changed tests in the pull request. | No | |
---
[BC-001]: ../business-case.md
[PP-001]: ../project-plan.md
[MIL-002]: ./mil-002-adopt-the-game.md
[MIL-004]: ./mil-004-high-score-file.md
[021-snake-game]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/021-snake-game
docs/milestones/mil-004-high-score-file.md
+85
View File
@@ -0,0 +1,85 @@
# MIL-004: High score file
## 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 | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version, reviewed in RC-007 (Go) | pending |
---
## Purpose
This gate decides whether the high score survives between games: it is read from `data.txt` with `with open(...)` when the scoreboard is made, converted from text to an integer, and written back to the file when a new high score is reached. It also decides the behaviour where the lecture is silent: a missing, empty or damaged file. The work is delivered on the branch `mil-004-high-score-file` and one pull request.
## Deliverable
Changed `src/snake_game/scoreboard.py` and `constants.py`, functions that read and write the high score, and tests that use a temporary file. The game, started again after a new high score, shows that high score.
## Go / No-Go Criteria
| # | Criterion (objectively checkable) | Go | No-Go |
| --- | --- | --- | --- |
| 1 | The high score is read at the start | `Scoreboard()` reads the file named by the constant `HIGH_SCORE_FILE` (`data.txt`) with a `with` statement, converts the text with `int` and shows the value as `High Score` | The value is not read, the file is opened without `with`, or the text is not converted |
| 2 | A new high score is written | When `reset` finds a score above the high score, the file holds the new value as text; a lower or equal score does not write the file | The file is not written, is written for a lower score, or holds something other than the number |
| 3 | A missing file is created | Starting without `data.txt` shows `High Score: 0` and leaves a `data.txt` that holds `0` | A traceback, or no file |
| 4 | A damaged file reads as 0 | An empty file, a file with text that is not a whole number and a negative number all give a high score of 0 without a traceback | A traceback, or a negative high score |
| 5 | The path is a parameter | The file name is a constant used as the default of a parameter, and every test passes a temporary path | A test uses the real `data.txt` |
| 6 | The high score survives a restart | S01 reaches a new high score, closes the window, starts `python -m snake_game` again and sees the same high score | The value is lost |
| 7 | `data.txt` is not tracked | `git check-ignore data.txt` lists it and no `data.txt` is in the change | The file is tracked |
| 8 | Tests, lint, format and types are clean | `pytest`, `python -m ruff check src tests`, `python -m ruff format --check src tests` and `python -m mypy` exit 0, as in continuous integration (CI); no test opens a window | Any of them fails |
| 9 | `doxygen Doxyfile` builds | 0 warnings | Any warning |
| 10 | The code is reviewed | `RC-*` against `QC-PY-001` has the verdict `Go` | Verdict `No-Go` or `Go-with-conditions` |
| 11 | No secret is in the change | `.env` is not tracked and no token appears in any changed file | A token is found in the diff |
## Dependencies
| Depends on | Reason |
| --- | --- |
| [MIL-003] accepted and merged | `Scoreboard.reset` and the two scores exist there |
## Traceability
| Business Case objective / KPI / user story | Reference |
| --- | --- |
| Objective 5: the file read and written with `with` | [BC-001], criterion 4 in Success Criteria |
| Objective 6: a missing or damaged file | [BC-001], criterion 5 in Success Criteria |
| Objective 9: tests never touch the real file | [BC-001], criterion 6 in Success Criteria |
## Ownership
| Role | Stakeholder ID (SA) |
| --- | --- |
| Owner | S01 |
| Approving reviewer | S01 |
## Target Date
2026-10-21 — fourth of five gateways.
## Tasks
| # | Task | Summary | Needs its own Use Case/User Story? | Reference |
| --- | --- | --- | --- | --- |
| 1 | Add the high score file constant | Add `HIGH_SCORE_FILE: Final[str] = "data.txt"` to `constants.py` with a Doxygen comment, and a test of it. | No | |
| 2 | Read the high score from the file | Add a function that opens the file with `with open(path) as data`, reads it, converts the text with `int` and returns it; `Scoreboard.__init__` takes the path as a parameter with the constant as default and sets `high_score` from it. Tests with a temporary file. | No | |
| 3 | Write the high score to the file | In `Scoreboard.reset`, when a new high score is reached, open the file with `with open(path, mode="w") as data` and write the number as text. Tests check the file content after a higher, equal and lower score. | No | |
| 4 | Handle a missing or damaged file | A missing file is created holding `0`; an empty file, text that is not a whole number or a negative number read as 0 (objective 6 of the Business Case). Tests for each case. | No | |
| 5 | Keep the tests away from the real data.txt | Every test that makes a `Scoreboard` passes a pytest `tmp_path` file; a guard in `tests/conftest.py` fails a test that would open the default path. | No | |
| 6 | Document the high score file in the README | Describe in the Run section where `data.txt` is, that it is created at the first start, how to reset the high score (delete the file) and that it is not tracked by git. Serves S02. | No | |
| 7 | Verify the high score file end to end | Run `pytest`, `ruff check`, `ruff format --check`, `mypy` and `doxygen Doxyfile` in a fresh `.venv`, reach a high score, restart the game, delete and damage `data.txt` and start again, and record the results in the pull request. | No | |
---
[BC-001]: ../business-case.md
[PP-001]: ../project-plan.md
[MIL-003]: ./mil-003-continuous-play-and-high-score.md
[MIL-005]: ./mil-005-wiki-and-finish.md
[021-snake-game]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/021-snake-game
docs/milestones/mil-005-wiki-and-finish.md
+79
View File
@@ -0,0 +1,79 @@
# MIL-005: Wiki and finish
## Metadata
| Key | Value |
| --- | --- |
| ID | MIL-005 |
| CrossReference | [BC-001] |
| Language | en |
| Domain | it |
## Version History
| Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- |
| 2026-10-13 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version, reviewed in RC-008 (Go) | pending |
---
## Purpose
This gate decides whether the repository is finished: the wiki exists in English, Danish and Bahasa Melayu, the README matches the finished game, the repository page is complete, and the whole game has been checked end to end. The work is delivered on the branch `mil-005-wiki-and-finish` and one pull request.
## Deliverable
The folder `wiki/` with `Home.md`, `Home.da.md`, `Home.ms.md`, `_Sidebar.md` and the marker `.publish`, in the form of the wiki of `TirSystem/github-action` and of [021-snake-game]; the finished `README.md`; a checked description and topics.
## Go / No-Go Criteria
| # | Criterion (objectively checkable) | Go | No-Go |
| --- | --- | --- | --- |
| 1 | The wiki is in three languages | The wiki has the pages `Home` (English), `Home.da` (Danish, Dansk) and `Home.ms` (Bahasa Melayu), each with a short description of the game, its controls, the high score file and how to run it, a language switch at the top, and a `_Sidebar` that lists the three languages | A language is missing, or a page does not link to the other two |
| 2 | The wiki is published | `wiki/.publish` exists and, after the merge, the three pages are on the wiki of the repository | The pages are not on the wiki; a missing secret is reported to S01 |
| 3 | The README is finished | Every section of the template is filled, the commands match the game, and no sentence is out of date | A heading is missing or a sentence is out of date |
| 4 | The repository page is complete | Description non-empty and at least 5 topics on the git host | Description empty or fewer than 5 topics |
| 5 | The whole game works | `pytest`, `ruff`, `mypy` and `doxygen Doxyfile` are clean in a fresh clone, and S01 plays: collision, reset, high score kept after a restart | Any check fails |
| 6 | No runtime dependencies | `[project].dependencies` is empty | An entry is present |
| 7 | The code is reviewed | `RC-*` against `QC-PY-001` has the verdict `Go` | Verdict `No-Go` or `Go-with-conditions` |
| 8 | No secret is in the change | `.env` is not tracked and no token appears in any changed file | A token is found in the diff |
## Dependencies
| Depends on | Reason |
| --- | --- |
| [MIL-004] accepted and merged | The high score file exists there, and the wiki describes it |
## Traceability
| Business Case objective / KPI / user story | Reference |
| --- | --- |
| Objective 10: README | [BC-001], criteria 7 and 8 in Success Criteria |
| Objective 12: repository page and wiki | [BC-001], criterion 12 in Success Criteria |
| Objective 11: traceable steps | [BC-001], criterion 11 in Success Criteria |
## Ownership
| Role | Stakeholder ID (SA) |
| --- | --- |
| Owner | S01 |
| Approving reviewer | S01 |
## Target Date
2026-10-23 — last of five gateways; two buffer days follow.
## Tasks
| # | Task | Summary | Needs its own Use Case/User Story? | Reference |
| --- | --- | --- | --- | --- |
| 1 | Write the wiki pages in three languages | In the folder `wiki/`, as the wiki of `TirSystem/github-action` does, write `Home.md` (English), `Home.da.md` (Danish) and `Home.ms.md` (Bahasa Melayu), each with a short description of the game, its controls, the high score file and how to run it, and a language switch (English, Dansk, Bahasa Melayu) at the top; add `_Sidebar.md` that lists the three languages. Serves S03. | No | |
| 2 | Add the wiki publish marker | Add the empty marker `wiki/.publish`, which makes the instance's workflow copy the pages to the wiki of the repository when a pull request is merged to `main`. It needs the secret `TOKEN_FOR_GITEA_WIKI` of the organization; a token is never printed or typed, and a missing secret is reported to S01. | No | |
| 3 | Finish the README | Check every section of `README.md` against the finished game: set-up on the three systems, run, the controls, the two scores, `data.txt`, the tests, CI, Doxygen, layout and license; correct what is out of date. Serves S02 and S03. | No | |
| 4 | Check the repository description and topics again | Read the description and topics from the git host and compare them with the finished game; correct them with the Gitea API when they differ. | No | |
| 5 | Verify the finished game end to end | In a fresh clone follow the README alone: create the `.venv`, upgrade `pip`, install, run `pytest`, `ruff`, `mypy` and `doxygen Doxyfile`, play, restart, and record the results in the pull request. | No | |
---
[BC-001]: ../business-case.md
[PP-001]: ../project-plan.md
[MIL-004]: ./mil-004-high-score-file.md
[021-snake-game]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/021-snake-game