MIL-002 NATO converter: modelling, converter code, tests and Doxygen comments
User story, use case and SSD for "spell a word"; spell_word with try/except KeyError, generate_phonetic with the retry loop, console and CSV adapters, 49 pytest tests; MIL-002 and the modelling documents accepted with review records. Task: MIL-002#1 Task: MIL-002#2 Task: MIL-002#3 Task: MIL-002#4 Task: MIL-002#5 Task: MIL-002#6
This commit is contained in:
@@ -0,0 +1,76 @@
|
||||
# MIL-002 NATO converter
|
||||
|
||||
## Metadata
|
||||
| Key | Value |
|
||||
| --- | --- |
|
||||
| ID | MIL-002 |
|
||||
| CrossReference | [BC-001] |
|
||||
| Language | en |
|
||||
| Domain | it |
|
||||
|
||||
## Version History
|
||||
| Date | Status | Author | Reviewer | Change | Commit |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version, reviewed in RC-004 | pending |
|
||||
|
||||
---
|
||||
|
||||
## Purpose
|
||||
|
||||
Decide whether the console program does what the Day 30 assignment asks: read a word, print the NATO code word of each letter, and handle invalid input with exception handling (a `try`/`except` on the failed dictionary lookup) inside `generate_phonetic`, which keeps asking until the input is valid. Tested with pytest.
|
||||
|
||||
## Deliverable
|
||||
|
||||
The `nato_phonetic_alphabet` package with a runnable entry point, a test suite that passes, and Doxygen comments on every public item; plus the user story, use case and system sequence diagram of "spell a word".
|
||||
|
||||
## Go / No-Go Criteria
|
||||
|
||||
| # | Criterion (objectively checkable) | Go | No-Go |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | All 26 letters map to their code word and input is case-insensitive | pytest passes | Any test fails |
|
||||
| 2 | A character that is not a letter raises a caught `KeyError`; the program tells the user to enter letters of the alphabet only and asks again instead of crashing | pytest covers it and passes | Missing or failing |
|
||||
| 3 | The loader uses a dictionary comprehension, the converter a list comprehension, and the invalid input is handled with `try`/`except`, not with a pre-check | Code review confirms | Loops or pre-checks used instead |
|
||||
| 4 | The assignment's function names are kept in the public API | Names present in the module | Names missing |
|
||||
| 5 | The code review against `qc-programming-python.md` is a `Go` | `RC-*` verdict `Go` | `No-Go` |
|
||||
| 6 | `doxygen Doxyfile` reports no warnings | 0 warnings | Any warning |
|
||||
| 7 | Constants live in `constants.py`; `.env` is not imported by `src/` or `tests/` | Search confirms | Any hit |
|
||||
|
||||
## Dependencies
|
||||
|
||||
| Depends on | Reason |
|
||||
| --- | --- |
|
||||
| [MIL-001] | Project configuration, skeleton, CI and Doxyfile |
|
||||
|
||||
## Traceability
|
||||
|
||||
| Business Case objective / KPI / user story | Reference |
|
||||
| --- | --- |
|
||||
| O1, O3, O4 | [BC-001] |
|
||||
| Spell a word | US-001, UC-001 |
|
||||
|
||||
## Ownership
|
||||
|
||||
| Role | Stakeholder ID (SA) |
|
||||
| --- | --- |
|
||||
| Owner | S01 |
|
||||
| Approving reviewer | S01 |
|
||||
|
||||
## Target Date
|
||||
|
||||
2026-10-15 — inside the plan's window (2026-10-14 to 2026-10-16).
|
||||
|
||||
## Tasks
|
||||
|
||||
| # | Task | Summary | Needs its own Use Case/User Story? | Reference |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 1 | Model "spell a word" | Write US-001, UC-001 (brief) and the system sequence diagram for the user who types a word and receives its NATO code words, including the retry on invalid input. Domain concepts are only letter and code word, so no domain model is added. | Yes | US-001, UC-001 |
|
||||
| 2 | Load the NATO alphabet | Read the CSV with the standard library and build the letter-to-code-word dictionary with a dictionary comprehension (`load_nato_dict`), taking the file name from `constants.py`. | No | |
|
||||
| 3 | Convert a word to code words | Implement the assignment's `generate_phonetic`: it prompts for a word, builds the code words with a list comprehension inside a `try` block, catches the `KeyError` of a character that is not a letter, tells the user to enter letters of the alphabet only, and loops until the input is valid. The lookup and the prompt sit behind ports so the layers stay separate. | Yes | UC-001 |
|
||||
| 4 | Implement the console entry point | Prompt for a word, print the code words, ask again on invalid input; runnable as `python -m nato_phonetic_alphabet` and as the `nato-phonetic-alphabet` command. | Yes | UC-001 |
|
||||
| 5 | Write the pytest suite | Test all letters, mixed case, unknown characters, the loader (with a temporary CSV) and the entry point (with patched input and captured output). | No | |
|
||||
| 6 | Add Doxygen comments | Document every module, function and constant with Doxygen comments and confirm the build has no warnings. | No | |
|
||||
|
||||
---
|
||||
|
||||
[BC-001]: ../business-case.md
|
||||
[MIL-001]: ./mil-001-repository-foundation.md
|
||||
@@ -0,0 +1,75 @@
|
||||
# MIL-003 Documentation and publication
|
||||
|
||||
## Metadata
|
||||
| Key | Value |
|
||||
| --- | --- |
|
||||
| ID | MIL-003 |
|
||||
| CrossReference | [BC-001] |
|
||||
| Language | en |
|
||||
| Domain | it |
|
||||
|
||||
## Version History
|
||||
| Date | Status | Author | Reviewer | Change | Commit |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 2026-10-14 | Proposed | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version, adapted from the 026 NATO alphabet project | pending |
|
||||
|
||||
---
|
||||
|
||||
## Purpose
|
||||
|
||||
Decide whether S02 and S03 can understand, set up and run the project from its README and wiki without help, in English, Danish and Bahasa Malaysia.
|
||||
|
||||
## Deliverable
|
||||
|
||||
The `README.md` built from the framework template with screenshots, and a wiki in English, Danish and Bahasa Malaysia with the same pages and screenshots, published on the git host.
|
||||
|
||||
## Go / No-Go Criteria
|
||||
|
||||
| # | Criterion (objectively checkable) | Go | No-Go |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | `check-readme.sh` reports no finding for the README | Exit code 0 | Any finding |
|
||||
| 2 | The README steps (create `.venv`, upgrade pip, install, run, test) work on a fresh clone on Windows PowerShell | The run produces the expected output | A step fails |
|
||||
| 3 | Every wiki page exists in en, da and ms | `check-languages.sh` and a file listing agree | A page is missing |
|
||||
| 4 | The README and each wiki language show a screenshot | Image files exist and are linked | Missing |
|
||||
| 5 | The wiki is published and readable on the host | Page requests return success | Any page not found |
|
||||
| 6 | `doxygen Doxyfile` builds and the README says how | Exit code 0 and the section exists | Missing |
|
||||
|
||||
## Dependencies
|
||||
|
||||
| Depends on | Reason |
|
||||
| --- | --- |
|
||||
| [MIL-002] | The documentation describes the finished program |
|
||||
|
||||
## Traceability
|
||||
|
||||
| Business Case objective / KPI / user story | Reference |
|
||||
| --- | --- |
|
||||
| O2, O4, O5 | [BC-001] |
|
||||
|
||||
## Ownership
|
||||
|
||||
| Role | Stakeholder ID (SA) |
|
||||
| --- | --- |
|
||||
| Owner | S01 |
|
||||
| Approving reviewer | S01 |
|
||||
|
||||
## Target Date
|
||||
|
||||
2026-10-16 — the end of the plan's window.
|
||||
|
||||
## Tasks
|
||||
|
||||
| # | Task | Summary | Needs its own Use Case/User Story? | Reference |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 1 | Capture screenshots | Run the program and render its real output as PNG images (a word spelled, an invalid input retried) stored under `docs/images/` for the README and the wiki. | No | |
|
||||
| 2 | Write the README | Fill the framework README template: set-up on Windows PowerShell, Linux Debian and macOS with a local `.venv` and `python -m pip install --upgrade pip`, run, tests, continuous integration, Doxygen build, layout and licence. | No | |
|
||||
| 3 | Write the English wiki | Pages Home, Install, Usage and Development in English with screenshots, in the layout of the framework wiki. | No | |
|
||||
| 4 | Write the Danish wiki | The same pages in Danish with the `-da` suffix. | No | |
|
||||
| 5 | Write the Bahasa Malaysia wiki | The same pages in Bahasa Malaysia with the `-ms` suffix. | No | |
|
||||
| 6 | Publish the wiki | Push the pages to the repository's wiki on the git host and check that each page is readable. | No | |
|
||||
| 7 | Verify the set-up instructions | Follow the README from a fresh clone in a new `.venv`, run the program and the tests, and record the result in the review. | No | |
|
||||
|
||||
---
|
||||
|
||||
[BC-001]: ../business-case.md
|
||||
[MIL-002]: ./mil-002-nato-converter.md
|
||||
Reference in New Issue
Block a user