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

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

Browse Source 
Mode: autonomous; reviews RC-001 to RC-007 are not independent.
This commit is contained in:
Tirsvad
2026-10-13 15:23:29 +08:00
parent 788caae0e6
commit f1b3c034dc
19 changed files with 1225 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/milestones/mil-001-project-scaffold.md
+73
View File
@@ -0,0 +1,73 @@
# MIL-001 Project scaffold and tooling
## 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 | pending |
---
## Purpose
Decide whether the repository has the tooling baseline (ignore rules, project configuration, constants module, Doxygen configuration and continuous integration (CI)) on which the analysis code can be built and reviewed.
## Deliverable
A branch merged to `main` containing `.gitignore`, `pyproject.toml`, `src/squirrel/constants.py`, `Doxyfile`, a CI workflow, and the repository description and topics set on the git host.
## Go / No-Go Criteria
| # | Criterion (objectively checkable) | Go | No-Go |
| --- | --- | --- | --- |
| 1 | `pyproject.toml` declares `requires-python = ">=3.13"` and no runtime dependencies | Present | Missing or has runtime dependencies |
| 2 | `.gitignore` ignores `.venv/`, `__pycache__/`, `.env` and `.pytest_cache/` | Present | Any missing |
| 3 | `python -m pytest` runs in a fresh `.venv` and exits 0 (collects at least the constants test) | Exit 0 | Non-zero exit |
| 4 | Repository description and at least 5 topics read back from the git host application programming interface (API) | Set | Not set |
| 5 | Review record for each reviewed artifact is `Go` | All Go | Any No-Go |
## Dependencies
| Depends on | Reason |
| --- | --- |
| BC-001, SA-001, PP-001 | The baseline must be accepted before milestones |
## Traceability
| Business Case objective / KPI / user story | Reference |
| --- | --- |
| Objective 4, Success Criteria 3 and 5 | [BC-001] |
| S03 concern: description and topics | [SA-001] |
## Ownership
| Role | Stakeholder ID (SA) |
| --- | --- |
| Owner | S01 |
| Approving reviewer | S01 |
## Target Date
2026-10-14 — one day after the plan, inside the single-day effort in the Business Case cost assessment
## Tasks
| # | Task | Summary | Needs its own Use Case/User Story? | Reference |
| --- | --- | --- | --- | --- |
| 1 | Add Python .gitignore | Add the standard Python ignore rules plus `.env`, `.venv/` and Doxygen output (`docs/doxygen/`), so tokens and build output never reach the repository. | No | |
| 2 | Add pyproject.toml | Configure the `squirrel` package in a `src/` layout: `requires-python >=3.13`, no runtime dependencies, an optional `dev` extra with pytest, and pytest `pythonpath` and `testpaths`. This is the single configuration file the Business Case constraints require. | No | |
| 3 | Add constants module | Create `src/squirrel/constants.py` holding file names, column names and fur colour values so no literal is repeated in the code, as the constraint requires. Add a first test that imports it. | No | |
| 4 | Add Doxyfile | Create a `Doxyfile` that reads `src/` and writes to `docs/doxygen/`, with Python optimisation enabled, so the source documentation can be built with `doxygen Doxyfile`. | No | |
| 5 | Add CI workflow | Add a Gitea Actions workflow that sets up Python 3.13, creates a venv, upgrades pip, installs the dev extra and runs pytest on push and pull request. It backs the "Continuous integration" section of the README. | No | |
| 6 | Set repository description and topics | Use the Gitea API with the token from `.env` (read by the shell only, never by the project) to set a description and topics such as `python`, `csv`, `squirrel-census`, `udemy`, `100-days-of-code`, `pytest`. Satisfies stakeholder S03. | No | |
---
[BC-001]: ../business-case.md
docs/milestones/mil-002-census-analysis.md
+75
View File
@@ -0,0 +1,75 @@
# MIL-002 Squirrel census analysis
## 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 | pending |
---
## Purpose
Decide whether the squirrel census analysis is modelled, implemented and tested well enough to produce the assignment result, `squirrel_count.csv`, from the 2018 census file.
## Deliverable
A branch merged to `main` containing the user story, use case, system sequence diagram and domain model, ADR-0001, the `squirrel` package with its command line entry point, the pytest tests, the census file under `data/` and the generated `squirrel_count.csv`.
## Go / No-Go Criteria
| # | Criterion (objectively checkable) | Go | No-Go |
| --- | --- | --- | --- |
| 1 | Running the program on the 2018 census file writes `squirrel_count.csv` with Gray 2473, Cinnamon 392, Black 103 | Matches | Differs |
| 2 | `python -m pytest` exits 0 and covers reading, counting, summary and export | Exit 0 | Failure or a function untested |
| 3 | The package imports no third-party module (checked by `pyproject.toml` and a test) | None | Any import |
| 4 | Source review against `qc-programming-python` has verdict `Go` | Go | No-Go |
| 5 | Model artifacts (user story (US), use case (UC), system sequence diagram (SSD), domain model (DM)) and ADR-0001 have review verdict `Go` | All Go | Any No-Go |
## Dependencies
| Depends on | Reason |
| --- | --- |
| MIL-001 | Tooling, constants and test infrastructure are needed first |
## Traceability
| Business Case objective / KPI / user story | Reference |
| --- | --- |
| Objectives 1 and 2, Success Criteria 1, 2 and 3 | [BC-001] |
## Ownership
| Role | Stakeholder ID (SA) |
| --- | --- |
| Owner | S01 |
| Approving reviewer | S01 |
## Target Date
2026-10-15 — one day after MIL-001, inside the single-day effort
## Tasks
| # | Task | Summary | Needs its own Use Case/User Story? | Reference |
| --- | --- | --- | --- | --- |
| 1 | Write user story and use case | Write US-001 and brief UC-001 "Count squirrels by fur colour": the participant supplies the census file and receives `squirrel_count.csv`. Needed because it is a goal an actor pursues. | No | |
| 2 | Model the interaction and concepts | Create `ssd.md` and `dm.md` in `docs/uc-001/`, then reconcile `docs/domain-model.md`. Concepts: Census file, Sighting, Fur colour, Colour count, Summary. | No | UC-001 |
| 3 | Record ADR-0001 standard library instead of Pandas | Decide to use the `csv` module and `collections.Counter` so the repository has no runtime dependencies (S03), while the function names follow the lecture steps (S02). | No | |
| 4 | Read the census file | Implement `read_csv(path)` returning the sightings with the primary fur colour column, using only the standard library. The file is read as UTF-8. | Yes | UC-001 |
| 5 | Count squirrels by fur colour | Implement `count_by_fur_color(rows, colors)` returning the count for gray, cinnamon and black, using the values defined in `constants.py`. | Yes | UC-001 |
| 6 | Build the summary and export it | Implement `build_summary(counts)` and `write_csv(summary, path)` producing `squirrel_count.csv` with the columns `Fur Color` and `Count`, mirroring the lecture's DataFrame-to-comma-separated-values (CSV) step. | Yes | UC-001 |
| 7 | Add the command line entry point | Add `python -m squirrel [input] [output]` with the census file path defaulting under `data/` and the output defaulting to `squirrel_count.csv`. Exit non-zero with a message when the input is missing. | Yes | UC-001 |
| 8 | Add pytest tests with fixture rows | Test each function with a small fixture CSV file so the tests run without the 730 kilobytes (KB) census file, plus one test that checks the real census file counts when the file is present. | No | |
| 9 | Add the census file and generate the result | Copy the 2018 census file into `data/` and run the program once to produce `squirrel_count.csv`, so others can run the project without downloading the file. | No | |
---
[BC-001]: ../business-case.md
docs/milestones/mil-003-documentation.md
+71
View File
@@ -0,0 +1,71 @@
# MIL-003 README, source documentation and screenshots
## 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 | pending |
---
## Purpose
Decide whether a newcomer (S02, S03) can set up, run, test and understand the project from the README and the generated source documentation alone.
## Deliverable
A branch merged to `main` containing `README.md` with the requested sections, Doxygen comments in the source that build cleanly, and screenshots stored under `docs/images/` and used in the README.
## Go / No-Go Criteria
| # | Criterion (objectively checkable) | Go | No-Go |
| --- | --- | --- | --- |
| 1 | README contains the sections Requirements, Set up (Windows PowerShell, Linux Debian, MacOS), Run, Run the tests, Continuous integration, Build the source documentation, Project layout, License | All present | Any missing |
| 2 | README documents creating a `.venv` and `python -m pip install --upgrade pip` | Present | Missing |
| 3 | `doxygen Doxyfile` completes with no warnings (when Doxygen is installed) | No warnings | Warnings |
| 4 | README shows at least one screenshot of the real program output | Present | Missing |
| 5 | Commands in the README were executed in a fresh `.venv` in this session | Verified | Not run |
## Dependencies
| Depends on | Reason |
| --- | --- |
| MIL-002 | The README documents a working program |
## Traceability
| Business Case objective / KPI / user story | Reference |
| --- | --- |
| Objectives 3 and 4, Success Criterion 4 | [BC-001] |
| S02 and S03 concerns on README | [SA-001] |
## Ownership
| Role | Stakeholder ID (SA) |
| --- | --- |
| Owner | S01 |
| Approving reviewer | S01 |
## Target Date
2026-10-16 — one day after MIL-002
## Tasks
| # | Task | Summary | Needs its own Use Case/User Story? | Reference |
| --- | --- | --- | --- | --- |
| 1 | Add Doxygen comments to the source | Document every module, function and constant with Doxygen comment blocks (`##` and `@param`/`@return`) so the Doxyfile produces useful output. | No | |
| 2 | Write README.md | Write the README from the framework template using the section list required by the Product Owner, including the venv and pip upgrade instructions for Windows PowerShell, Linux Debian and MacOS. | No | |
| 3 | Create screenshots | Render images of the real command output (program run and test run) as Portable Network Graphics (PNG) files under `docs/images/`, and reference them from the README and later the wiki. | No | |
| 4 | Verify the README commands | Follow the README in a fresh `.venv` and record the result in the review record, so the instructions are known to work. | No | |
---
[BC-001]: ../business-case.md
docs/milestones/mil-004-wiki-publication.md
+71
View File
@@ -0,0 +1,71 @@
# MIL-004 Wiki and publication
## 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 | pending |
---
## Purpose
Decide whether the repository is published with a wiki in English, Danish and Bahasa Malaysia and whether the final repository metadata is correct.
## Deliverable
Wiki pages `Home`, `Install`, `Usage` and `Description` in English plus `-da` and `-ms` variants following the framework wiki layout, with screenshots, pushed to the wiki of the repository, and a final verification of description and topics.
## Go / No-Go Criteria
| # | Criterion (objectively checkable) | Go | No-Go |
| --- | --- | --- | --- |
| 1 | Each wiki page exists in English, Danish (`-da`) and Bahasa Malaysia (`-ms`) | All present | Any missing |
| 2 | The sidebar links every page in all three languages | All linked | Missing link |
| 3 | Wiki pages are on the git host wiki, or kept under `docs/wiki/` with the failure reported | Published or reported | Neither |
| 4 | Screenshots appear on the wiki pages | Present | Missing |
## Dependencies
| Depends on | Reason |
| --- | --- |
| MIL-003 | The wiki reuses README content and screenshots |
## Traceability
| Business Case objective / KPI / user story | Reference |
| --- | --- |
| Objective 5, Success Criteria 4 and 5 | [BC-001] |
| S02 and S03 communication needs | [SA-001] |
## Ownership
| Role | Stakeholder ID (SA) |
| --- | --- |
| Owner | S01 |
| Approving reviewer | S01 |
## Target Date
2026-10-16 — same day as MIL-003
## Tasks
| # | Task | Summary | Needs its own Use Case/User Story? | Reference |
| --- | --- | --- | --- | --- |
| 1 | Write English wiki pages | Create `Home`, `Install`, `Usage` and `Description` pages and a `_Sidebar`, after the structure of the framework wiki and the TirSystem github-action wiki example. | No | |
| 2 | Write Danish wiki pages | Translate the English pages into Danish with the `-da` suffix and a language switch in the sidebar. | No | |
| 3 | Write Bahasa Malaysia wiki pages | Translate the English pages into Bahasa Malaysia with the `-ms` suffix and a language switch in the sidebar. | No | |
| 4 | Add screenshots to the wiki | Add the images from `docs/images/` to the pages of all three languages. | No | |
| 5 | Publish the wiki and verify metadata | Push the pages to the repository wiki with the token from `.env` and read back the repository description and topics from the API. | No | |
---
[BC-001]: ../business-case.md