From c0c3940551db0d7d96492cc734976d0436051ff9 Mon Sep 17 00:00:00 2001 From: Jens Tirsvad Nielsen Date: Mon, 5 Oct 2026 00:24:54 +0800 Subject: [PATCH] Add planning baseline: BC, SA, PP and MIL-001 to MIL-003 Draft and accept the Business Case, Stakeholder Analysis (S01-S03) and Project Plan for the Day 15 coffee machine assignment. Add three milestones with 17 tasks, synced to the git host as Milestones 40-42 and Issues #1-#17. Register PP and MIL in the artifact registry and set the PO language to en. No issue closed: planning only, no code changed. --- .gitmodules | 3 + docs/artifact-registry.md | 43 ++++++ docs/business-case.md | 133 ++++++++++++++++++ docs/milestones/mil-001-project-setup.md | 67 +++++++++ .../milestones/mil-002-coffee-machine-core.md | 71 ++++++++++ .../mil-003-quality-and-publication.md | 68 +++++++++ docs/project-plan.md | 87 ++++++++++++ docs/stakeholder-analysis.md | 77 ++++++++++ framework | 1 + 9 files changed, 550 insertions(+) create mode 100644 .gitmodules create mode 100644 docs/artifact-registry.md create mode 100644 docs/business-case.md create mode 100644 docs/milestones/mil-001-project-setup.md create mode 100644 docs/milestones/mil-002-coffee-machine-core.md create mode 100644 docs/milestones/mil-003-quality-and-publication.md create mode 100644 docs/project-plan.md create mode 100644 docs/stakeholder-analysis.md create mode 160000 framework diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..a759dc9 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "framework"] + path = framework + url = ssh://git@git.tirsystem.com:10022/TirSystem/SQA-QC-Framework.git diff --git a/docs/artifact-registry.md b/docs/artifact-registry.md new file mode 100644 index 0000000..c51c27b --- /dev/null +++ b/docs/artifact-registry.md @@ -0,0 +1,43 @@ +# Artifact Registry + +This project's artifact state. Types, short names and `CrossReference +Candidates` come from the framework catalog +(`framework/registry/artifact-catalog.md`); this file only records where +each document lives in *this* project and the next version to use. + +Delete rows for types you don't use. Add a row the first time you create a +document of a type. `Primary File` may contain a glob (e.g. +`docs/uc-*/uc.md`); `framework/scripts/find-crossreferences.sh` reads it. + +| Short Name | Artifact Type | Primary File | Next Available Version | +| --- | --- | --- | --- | +| BC | Business Case | docs/business-case.md | 002 | +| SA | Stakeholder Analysis | docs/stakeholder-analysis.md | 002 | +| PP | Project Plan | docs/project-plan.md | 002 | +| MIL | Milestone / Gateway | docs/milestones/*.md | 004 | + +## Languages + +Set the PO language when the project starts; `project-planning` asks for it +if it is missing. A translated artifact is named `..md` +(for example `business-case.da.md`); the English file stays the source. + +| Setting | Value | +| --- | --- | +| PO language | en | +| High-level register | IT Executive English | +| Technical register | IT Professional English | + +| Artifact types | Register | Also kept as a PO-language file | +| --- | --- | --- | +| BC, KPI, PP, MIL | IT Executive English | Yes | +| SA, BMC, BPMN, UCD, US, UC, SSD, DM, RA, GOV, DICT | IT Professional English | Yes | +| OC, SD, DCD, ERD, ADR, TM, RC, QC, source code | IT Professional English | No | + +## Notes + +- "Next Available Version" is the zero-padded (3-digit) version to use the + *next* time a new document of that type is created. Increment it only when + a brand-new document is created, not when an existing document's + `## Version History` gets a row. +- `ADR` uses 4 digits (`0001`); `RC` is sequential across all artifact types. diff --git a/docs/business-case.md b/docs/business-case.md new file mode 100644 index 0000000..a34ee5b --- /dev/null +++ b/docs/business-case.md @@ -0,0 +1,133 @@ +# Business Case + +## Metadata +| Key | Value | +| --- | --- | +| ID | BC-001 | +| CrossReference | [SA-001] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-05 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending | + +--- + +## Executive Summary + +Build a console coffee machine in Python as the Day 15 assignment of Udemy's +"100 Days of Code: The Complete Python Pro Bootcamp". The program serves +espresso, latte and cappuccino, accepts US coins, tracks water, milk and coffee +and prints a report on request. It is published as a readable, runnable +reference for other course participants and as a portfolio piece. + +## Methodological and Standards Foundation + +Planning follows the SQA/QC framework mounted at `framework/` (plan first, then +code). Quality is described with ISO/IEC 25010:2023 characteristics. Code uses +the `coding-conventions` skill and Doxygen comments. + +## Problem Statement + +The assignment specification is long and detail-heavy (resources, coins, +refunds, change). Solutions shared by participants vary widely in structure and +readability, and a single `main.py` script is hard to test. + +## Business Opportunity + +A small, well-structured and tested solution is a clear example for other +participants and for viewers browsing the repository. + +## Objectives + +1. Implement the full assignment behaviour: `report`, `off`, drink selection, resource check, coin processing, change, profit. +2. Keep the assignment's function names so participants can compare solutions. +3. Cover the behaviour with automated pytest tests. +4. Document how to set up a local `.venv` and run the program and tests. +5. Publish the repository with a description, topics and README. + +## Scope + +### In Scope + +- Console program under `src/` with a `constants.py` for menu, coins and starting resources. +- pytest tests under `tests/`. +- `pyproject.toml`, Python `.gitignore`, `Doxyfile`, `README.md`. +- Project documents under `docs/`. +- Repository description and topics on the git host. + +### Out of Scope + +- Graphical or web interface. +- Payment other than the four US coins. +- Persistence of resources or profit between runs. +- Runtime dependencies. + +## Expected Benefits + +### Tangible Benefits + +- Completed Day 15 assignment. +- Runnable code with tests and setup instructions. + +### Intangible Benefits + +- Practice with planning, testing and Python project layout. +- A reusable template for later course projects. + +## Strategic Alignment + +Supports the learner's goal of finishing the 100 Days of Code course with +professional project hygiene, and the goal of sharing readable solutions. + +## Success Criteria + +| # | Criterion | Target | Measure | +| --- | --- | --- | --- | +| 1 | Assignment behaviours implemented | 100% of listed behaviours | Manual run against the specification | +| 2 | Tests pass | All pytest tests green | `python -m pytest` | +| 3 | Runtime dependencies | 0 | `pyproject.toml` `dependencies` is empty | +| 4 | Setup documented | A new reader can run program and tests from README | README walkthrough | +| 5 | Repository metadata | Description and at least 3 topics set | Repository page | + +## Risks + +| Risk | Impact | Mitigation | +| --- | --- | --- | +| Floating-point rounding in coin totals | Wrong change or refund | Compute money in cents (integers) internally | +| Token in `.env` leaks | Account compromise | `.env` is gitignored, never imported or tested by the project | +| Scope creep beyond the assignment | Delay | Out of Scope list above | + +## Assumptions + +- Python 3.13 or newer is installed. +- The git host repository already exists and is reachable. + +## Constraints + +- Python greater than 3.13 as requested, `venv` for environments, pytest for tests. +- Constants live in `constants.py`. +- Source files use Doxygen comments. +- Nothing is committed or pushed unless the user asks. + +## Cost–Benefit Assessment + +| Costs | Benefits | +| --- | --- | +| A few hours of the learner's time | Finished, tested, shareable assignment (qualitative; no money involved) | + +## Stakeholders + +| Stakeholder ID (SA) | Interest in this project | +| --- | --- | +| S01 | Completes the assignment and owns the plan, code and review | +| S02 | Reads and runs the code, compares solutions | +| S03 | Browses the repository for ideas | + +## Recommendation + +Proceed — the scope is small, well specified and delivers a reusable example. + +--- + +[SA-001]: ./stakeholder-analysis.md diff --git a/docs/milestones/mil-001-project-setup.md b/docs/milestones/mil-001-project-setup.md new file mode 100644 index 0000000..ffebd5d --- /dev/null +++ b/docs/milestones/mil-001-project-setup.md @@ -0,0 +1,67 @@ +# MIL-001 Project Setup + +## Metadata +| Key | Value | +| --- | --- | +| ID | MIL-001 | +| CrossReference | [BC-001] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-05 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending | + +--- + +## Purpose + +Decide whether the project skeleton and tooling are ready for feature work. + +## Deliverable + +Repository skeleton: `src/`, `tests/`, `docs/`, `pyproject.toml`, `.gitignore`, `Doxyfile`, README with venv instructions. + +## Go / No-Go Criteria + +| # | Criterion (objectively checkable) | Go | No-Go | +| --- | --- | --- | --- | +| 1 | `pip install -e .[dev]` succeeds in a fresh `.venv` on Python 3.13+ | Succeeds | Fails | +| 2 | `python -m pytest` runs without configuration errors | Runs | Errors | +| 3 | README documents `.venv` creation and `python -m pip install --upgrade pip` | Present | Missing | + +## Dependencies + +| Depends on | Reason | +| --- | --- | +| None | First phase | + +## Traceability + +| Business Case objective / KPI / user story | Reference | +| --- | --- | +| Objective 4 (documented setup) | [BC-001] | + +## Ownership + +| Role | Stakeholder ID (SA) | +| --- | --- | +| Owner | S01 | +| Approving reviewer | S01 | + +## Target Date + +2026-10-07 — within the short course-assignment timeline in [BC-001]. + +## Tasks + +| # | Task | Summary | Needs its own Use Case/User Story? | Reference | +| --- | --- | --- | --- | --- | +| 1 | Create pyproject.toml | Declare the package with `requires-python >=3.13`, an empty runtime dependency list, a `dev` extra with pytest, and pytest config (`testpaths`, `pythonpath = ["src"]`). | No | Objective 4 | +| 2 | Verify Python .gitignore | Confirm the existing `.gitignore` ignores `.venv/`, `.env`, `__pycache__/`, `.pytest_cache/` and Doxygen output (`docs/doxygen/`); add what is missing. | No | Objective 4 | +| 3 | Add Doxyfile | Create a Doxyfile that scans `src/`, writes HTML to `docs/doxygen/`, and is configured for Python (`OPTIMIZE_OUTPUT_JAVA`, `EXTRACT_ALL`). Source comments use Doxygen style. | No | Objective 4 | +| 4 | Create src and tests skeleton | Create `src/coffee_machine/` with `__init__.py`, `constants.py` and `main.py` stubs, and `tests/` with a smoke test, following the `coding-conventions` skill. | No | Objective 1 | +| 5 | Write README with setup instructions | Write README.md: project description, how to create and use a local `.venv`, `python -m pip install --upgrade pip`, install, run, test and Doxygen. The README template from the request was not supplied; ask for it before writing. | No | Objective 4 | + +--- + +[BC-001]: ../business-case.md diff --git a/docs/milestones/mil-002-coffee-machine-core.md b/docs/milestones/mil-002-coffee-machine-core.md new file mode 100644 index 0000000..8326d8b --- /dev/null +++ b/docs/milestones/mil-002-coffee-machine-core.md @@ -0,0 +1,71 @@ +# MIL-002 Coffee Machine Core + +## Metadata +| Key | Value | +| --- | --- | +| ID | MIL-002 | +| CrossReference | [BC-001] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-05 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending | + +--- + +## Purpose + +Decide whether the machine behaves as the assignment specification requires. + +## Deliverable + +Working console program in `src/coffee_machine/` implementing report, off, drink selection, resource check, coin processing, change and profit. + +## Go / No-Go Criteria + +| # | Criterion (objectively checkable) | Go | No-Go | +| --- | --- | --- | --- | +| 1 | Typing `report` prints water, milk, coffee and money | Matches spec format | Differs | +| 2 | A drink is refused when a resource is insufficient, naming the resource | Refused with message | Served or no message | +| 3 | Insufficient coins refund everything with the spec's refund message | Refunded | Drink served | +| 4 | Excess coins return correct change and add only the price to profit | Correct | Wrong amount | +| 5 | Typing `off` ends the program | Exits | Keeps running | + +## Dependencies + +| Depends on | Reason | +| --- | --- | +| MIL-001 | Skeleton and tooling must exist | + +## Traceability + +| Business Case objective / KPI / user story | Reference | +| --- | --- | +| Objectives 1, 2 | [BC-001] | + +## Ownership + +| Role | Stakeholder ID (SA) | +| --- | --- | +| Owner | S01 | +| Approving reviewer | S01 | + +## Target Date + +2026-10-10 — within the short course-assignment timeline in [BC-001]. + +## Tasks + +| # | Task | Summary | Needs its own Use Case/User Story? | Reference | +| --- | --- | --- | --- | --- | +| 1 | Define constants | Put `MENU`, `COIN_VALUES` and `INITIAL_RESOURCES` in `constants.py`, from the assignment's starting data. | No | Objective 1 | +| 2 | Implement report | Print water (ml), milk (ml), coffee (g) and money ($) in the assignment's format. | No | Objective 1 | +| 3 | Implement is_resource_sufficient | Check an order against current resources; print the not-enough-resource message and return False when short. Keep the assignment's function name. | No | Objective 2 | +| 4 | Implement process_coins | Ask for quarters, dimes, nickels and pennies and return the total, using integer cents internally to avoid float errors. | No | Objective 1 | +| 5 | Implement is_transaction_successful | Compare payment with cost; refund if short, otherwise return change rounded to 2 decimals and add the cost to profit. | No | Objective 1 | +| 6 | Implement make_coffee | Deduct the drink's ingredients from resources and print the enjoy message. | No | Objective 1 | +| 7 | Implement main loop | Prompt for espresso/latte/cappuccino, handle `report`, `off` and invalid input, and wire the functions together. | No | Objective 1 | + +--- + +[BC-001]: ../business-case.md diff --git a/docs/milestones/mil-003-quality-and-publication.md b/docs/milestones/mil-003-quality-and-publication.md new file mode 100644 index 0000000..4513841 --- /dev/null +++ b/docs/milestones/mil-003-quality-and-publication.md @@ -0,0 +1,68 @@ +# MIL-003 Quality and Publication + +## Metadata +| Key | Value | +| --- | --- | +| ID | MIL-003 | +| CrossReference | [BC-001] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-05 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending | + +--- + +## Purpose + +Decide whether the project is tested, documented and ready to share. + +## Deliverable + +pytest suite, Doxygen output, finished README, and repository description and topics on the git host. + +## Go / No-Go Criteria + +| # | Criterion (objectively checkable) | Go | No-Go | +| --- | --- | --- | --- | +| 1 | `python -m pytest` passes with all tests green | All pass | Any failure | +| 2 | `doxygen Doxyfile` runs without warnings on `src/` | No warnings | Warnings | +| 3 | Repository has a description and at least 3 topics | Set | Missing | +| 4 | `pyproject.toml` lists no runtime dependencies and `.env` is not imported or tested | Confirmed | Violated | + +## Dependencies + +| Depends on | Reason | +| --- | --- | +| MIL-002 | Behaviour must exist before it is tested and published | + +## Traceability + +| Business Case objective / KPI / user story | Reference | +| --- | --- | +| Objectives 3, 4, 5 | [BC-001] | + +## Ownership + +| Role | Stakeholder ID (SA) | +| --- | --- | +| Owner | S01 | +| Approving reviewer | S01 | + +## Target Date + +2026-10-12 — within the short course-assignment timeline in [BC-001]. + +## Tasks + +| # | Task | Summary | Needs its own Use Case/User Story? | Reference | +| --- | --- | --- | --- | --- | +| 1 | Write tests for resources and report | pytest tests for `report` output and `is_resource_sufficient` with sufficient and insufficient resources. | No | Objective 3 | +| 2 | Write tests for coins and transactions | pytest tests for `process_coins` (mocked input), refund, exact payment, change and profit updates. | No | Objective 3 | +| 3 | Write tests for make_coffee and main loop | pytest tests for resource deduction and for `off`, `report` and invalid input handling through mocked `input`. | No | Objective 3 | +| 4 | Generate and check Doxygen output | Run `doxygen Doxyfile`; fix undocumented or malformed comments. | No | Objective 4 | +| 5 | Set repository description and topics | Use the git host API with the token in `.env` (personal use only, never imported by the project) to set the description and topics, after the user confirms the exact text. | No | Objective 5 | + +--- + +[BC-001]: ../business-case.md diff --git a/docs/project-plan.md b/docs/project-plan.md new file mode 100644 index 0000000..f954a27 --- /dev/null +++ b/docs/project-plan.md @@ -0,0 +1,87 @@ +# Project Plan + +## Metadata +| Key | Value | +| --- | --- | +| ID | PP-001 | +| CrossReference | [BC-001], [SA-001], [MIL-001], [MIL-002], [MIL-003] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-05 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending | + +--- + +## Purpose + +Schedule the three phases that take the coffee machine from empty repository to +published project, within the short assignment timeline in [BC-001]. + +## Planning Assumptions + +- Week 1 starts 2026-10-05; the plan ends by 2026-10-12. +- Phase length: two to three days; S01 reviews each phase through a pull request (see [SA-001]). +- Each phase is one branch and one pull request. + +## Gateway Schedule + +| Gateway | Document | Window | Decision date | Owner | Stories | Main deliverable | Milestone | +| --- | --- | --- | --- | --- | --- | --- | --- | +| Project Setup | [MIL-001] | 2026-10-05 to 2026-10-07 | 2026-10-07 | S01 | none | Skeleton, tooling, README | [Milestone 40] | +| Coffee Machine Core | [MIL-002] | 2026-10-08 to 2026-10-10 | 2026-10-10 | S01 | none | Working program | [Milestone 41] | +| Quality and Publication | [MIL-003] | 2026-10-11 to 2026-10-12 | 2026-10-12 | S01 | none | Tests, Doxygen, published repo | [Milestone 42] | + +```plantuml +@startgantt +Project starts 2026-10-05 +[Project Setup] starts 2026-10-05 and ends 2026-10-07 +[Coffee Machine Core] starts 2026-10-08 and ends 2026-10-10 +[Quality and Publication] starts 2026-10-11 and ends 2026-10-12 +[MIL-001 Go/No-Go] happens 2026-10-07 +[MIL-002 Go/No-Go] happens 2026-10-10 +[MIL-003 Go/No-Go] happens 2026-10-12 +@endgantt +``` + +## Scope Coverage + +| Business Case scope item | Gateway | +| --- | --- | +| Console program with `constants.py` | [MIL-002] | +| pytest tests | [MIL-003] | +| `pyproject.toml`, `.gitignore`, `Doxyfile`, README | [MIL-001] | +| Project documents | Planning, before [MIL-001] | +| Repository description and topics | [MIL-003] | + +## Dependencies + +``` +MIL-001 -> MIL-002 -> MIL-003 +``` + +A No-Go moves all later dates by the same amount. + +## Plan Risks + +| Risk | Impact | Mitigation | +| --- | --- | --- | +| README template not supplied | README task blocked | Ask S01 for the template before the task | +| Doxygen not installed locally | Cannot verify docs | Document the install step in README | + +## Open Issues + +- The README template referenced in the request ("template below") was not included. +- No use cases or user stories are written; tasks are plain technical tasks implementing the assignment specification. S01 can ask for a use case ("Order a drink") if wanted. +- Python ">3.13" is read as 3.13 or newer (`>=3.13`). + +--- + +[BC-001]: ./business-case.md +[SA-001]: ./stakeholder-analysis.md +[MIL-001]: ./milestones/mil-001-project-setup.md +[MIL-002]: ./milestones/mil-002-coffee-machine-core.md +[MIL-003]: ./milestones/mil-003-quality-and-publication.md +[Milestone 40]: https://git.tirsystem.com/Tirsvad-Udemy-100_days_of_code/015-coffee_machine/milestone/40 +[Milestone 41]: https://git.tirsystem.com/Tirsvad-Udemy-100_days_of_code/015-coffee_machine/milestone/41 +[Milestone 42]: https://git.tirsystem.com/Tirsvad-Udemy-100_days_of_code/015-coffee_machine/milestone/42 diff --git a/docs/stakeholder-analysis.md b/docs/stakeholder-analysis.md new file mode 100644 index 0000000..c1681b3 --- /dev/null +++ b/docs/stakeholder-analysis.md @@ -0,0 +1,77 @@ +# Stakeholder Analysis + +## Metadata +| Key | Value | +| --- | --- | +| ID | SA-001 | +| CrossReference | [BC-001] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-05 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending | + +--- + +## Purpose + +Identify who is affected by the coffee machine project and what each needs, +using a power/interest grid (Manage Closely, Keep Satisfied, Keep Informed, +Monitor). + +## Stakeholder Summary Table + +| ID | Name | Role/Title | Organization | Power Level | Interest Level | Quadrant | Primary Concern (Business Language) | +| --- | --- | --- | --- | --- | --- | --- | --- | +| S01 | Jens Tirsvad Nielsen | Course participant: Product Owner, developer and reviewer | Self | High | High | Manage Closely | Finish the assignment correctly with clean structure | +| S02 | Udemy coursists | Fellow course participants | Udemy course community | Low | High | Keep Informed | Readable, runnable code with the assignment's function names, and README run instructions | +| S03 | GitHub viewers | Repository browsers | Public | Low | Low | Monitor | A clear repository description, topics and README, and no runtime dependencies | + +## Power/Interest Classification Rationale + +- **Manage Closely (S01):** decides scope, writes and reviews everything. +- **Keep Informed (S02):** cannot change the project but depend on its clarity. +- **Monitor (S03):** casual visitors; a good first impression is enough. + +## Primary Concerns and FURPS+ Mapping + +| ID | Concern | FURPS+ attribute | +| --- | --- | --- | +| S01 | Correct behaviour per specification | Functionality | +| S01 | Tested and maintainable | Supportability | +| S02 | Easy to read and run | Usability | +| S02 | Same function names as the assignment | Functionality | +| S03 | Quick understanding of the repository | Usability | +| S03 | No dependencies to install | Implementation (+) | + +## Communication Requirements + +| Stakeholder | Channel | Frequency | Deliverable | Phase | +| --- | --- | --- | --- | --- | +| S01 | Chat and pull request review | Per milestone | Working tree changes, PR | MIL-001 to MIL-003 | +| S02 | README | At publication | Run and test instructions | MIL-003 | +| S03 | Repository page | At publication | Description, topics, README | MIL-003 | + +## Conflicting Interests and Mitigations + +| Conflict | Mitigation | +| --- | --- | +| S02 want assignment-style function names; S01 wants testable structure | Keep the assignment's names (`is_resource_sufficient`, `process_coins`, `is_transaction_successful`, `make_coffee`) and make them pure/parameterised so they are testable | + +## Traceability Analysis + +| Stakeholder | Goal / use case | Business Case objective | +| --- | --- | --- | +| S01 | Operate the machine (order, report, off) | [BC-001] objectives 1, 3 | +| S02 | Read and run the code | [BC-001] objectives 2, 4 | +| S03 | Browse the repository | [BC-001] objective 5 | + +## Sign-Off + +| Stakeholder | Decision | Date | +| --- | --- | --- | +| S01 | Pending review | | + +--- + +[BC-001]: ./business-case.md diff --git a/framework b/framework new file mode 160000 index 0000000..14d221e --- /dev/null +++ b/framework @@ -0,0 +1 @@ +Subproject commit 14d221ec1cfd3966611a3eff6a607ef1964526c2