Merge pull request 'MIL-003 Documentation and publication' (#22 ) from mil-003-documentation-and-publication into main

Merge pull request MIL-003 Documentation and publication (#22)
Resolve pending commit links for MIL-003
2026-10-14 13:40:58 +02:00 · 2026-10-14 19:40:08 +08:00 · 2026-10-14 19:40:06 +08:00 · 2026-10-14 19:38:55 +08:00 · 2026-10-14 13:36:39 +02:00
22 changed files with 852 additions and 2 deletions
@@ -1,2 +1,207 @@
-# 030-nato-phonetic-alphabet
+# 🚀 NATO phonetic alphabet

+A console tool that spells a word with the NATO phonetic alphabet and handles invalid input with exception handling, the Day 30 assignment of Udemy's "100 Days of Code: The Complete Python Pro Bootcamp". It is written for fellow course participants and GitHub visitors who want a readable, tested, runnable solution that has no runtime dependencies.
+
+![The tool spelling the word Hello][screenshot-spell]
+
+## 📚 Table of Contents
+
+- [Overview](#-overview)
+- [Requirements](#-requirements)
+- [Setup](#-setup)
+- [Run](#-run)
+- [Tests](#-tests)
+- [Continuous integration](#-continuous-integration)
+- [Build the source documentation](#-build-the-source-documentation)
+- [Project layout](#-project-layout)
+- [License](#-license)
+- [Links](#-links)
+- [Appendix: Project documents](#-appendix-project-documents)
+
+## 🧭 Overview
+
+You type a word, the program prints the NATO code word of each letter. A character that is not a letter does not crash the program: the error is caught, you are told to enter letters only, and the program asks again.
+
+```text
+Enter a word: Hello
+Phonetic code words:
+Hotel
+Echo
+Lima
+Lima
+Oscar
+```
+
+How it works, in the course's terms:
+
+- `load_nato_dict` reads the supplied CSV file and builds the letter-to-code-word dictionary with a **dictionary comprehension**.
+- `spell_word` turns a word into its code words with a **list comprehension** inside a `try` block; a character that is not in the alphabet raises a `KeyError`, which the `except` block turns into an `InvalidWordError`.
+- `generate_phonetic` wraps the input and the error handling: it asks for a word, reports an invalid one and asks again until the word is valid.
+- The standard library `csv` module replaces Pandas, so the project has no runtime dependencies (see the architecture decision record [ADR-0001][ADR-0001]).
+
+The wiki explains installation, usage and development in English, Danish and Bahasa Malaysia: [wiki][wiki].
+
+## 📋 Requirements
+
+- Python 3.13 or newer, with the `venv` module.
+- Git, to clone the repository.
+- Optional: [Doxygen](https://www.doxygen.nl/) to build the source documentation.
+
+The program itself needs no packages. The development tools (pytest, ruff, mypy, import-linter) are installed by the `dev` extra.
+
+## 🛠️ Setup
+
+Clone the repository, then create a local virtual environment named `.venv` in its root, upgrade pip and install the project in editable mode with its development tools.
+
+### Windows PowerShell
+
+```powershell
+git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet.git
+cd 030-nato-phonetic-alphabet
+py -3.13 -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+If PowerShell refuses to run the activation script, allow it for this window only with `Set-ExecutionPolicy -Scope Process RemoteSigned`.
+
+### Linux Debian
+
+```bash
+sudo apt install git python3 python3-venv
+git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet.git
+cd 030-nato-phonetic-alphabet
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+Debian 13 (trixie) ships Python 3.13. On an older release install Python 3.13 first (for example with `pyenv`).
+
+### MacOS
+
+```bash
+brew install python@3.13 git
+git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet.git
+cd 030-nato-phonetic-alphabet
+python3.13 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+## ▶️ Run
+
+With the virtual environment active:
+
+```bash
+python -m nato_phonetic_alphabet
+```
+
+or, as the installed command:
+
+```bash
+nato-phonetic-alphabet
+```
+
+An invalid character asks for the word again:
+
+![A word with a digit is rejected, then a valid word is spelled][screenshot-retry]
+
+## 🧪 Tests
+
+Run the tests with the virtual environment active:
+
+```bash
+python -m pytest
+```
+
+The same checks that CI runs:
+
+```bash
+python -m ruff check .
+python -m mypy
+lint-imports
+```
+
+## 🔄 Continuous integration
+
+The workflow [`.gitea/workflows/ci.yml`](.gitea/workflows/ci.yml) runs on every push to `main` or a `mil-*` branch and on every pull request that touches source, tests or configuration. It sets up Python 3.13, creates a virtual environment, installs the project with the `dev` extra, and runs ruff, mypy and pytest.
+
+## 📖 Build the source documentation
+
+The source is documented with Doxygen comments. From the repository root:
+
+```bash
+doxygen Doxyfile
+```
+
+Open `build/html/index.html` in a browser. The `build/` folder is ignored by git.
+
+## 🗂️ Project layout
+
+```text
+src/nato_phonetic_alphabet/
+  constants.py        every literal of the program
+  main.py             composition root and entry point
+  __main__.py         python -m nato_phonetic_alphabet
+  domain/             spell_word, the spelling rule with try/except (no input or output)
+  application/        generate_phonetic (input and retry loop) and its port
+  adapters/           CSV reader and console
+  data/               nato_phonetic_alphabet.csv
+tests/                pytest tests, mirroring src/
+docs/                 project documents (see the appendix)
+docs/wiki/            wiki pages in en, da and ms
+.gitea/workflows/     CI workflow
+pyproject.toml        project configuration
+Doxyfile              Doxygen configuration
+```
+
+## 📄 License
+
+GNU Affero General Public License v3.0 or later. See [LICENSE](LICENSE).
+
+## 🔗 Links
+
+- [Repository][repository]
+- [Documentation][documentation]
+- [Issue tracker][issues]
+
+## 📎 Appendix: Project documents
+
+The documents a newcomer needs, in reading order.
+
+| Document | What it tells you |
+| --- | --- |
+| [AGENTS.md][agents] | The rules AI agents follow in this repository |
+| [Business Case][BC-001] | Why the project exists, its scope and success criteria |
+| [Stakeholder Analysis][SA-001] | Who is involved; the stakeholder IDs used for owners and reviewers |
+| [Project Plan][PP-001] | The gateways and their schedule |
+| [Milestones][milestones] | One document per gateway: Go/No-Go criteria and tasks |
+| [Architecture decisions][adr] | Why the data is read with the standard library and which analysis documents were skipped |
+| [Artifact registry][registry] | Where each artifact type lives, the next version, the PO language and domain |
+| [Traceability matrix][TM-001] | How the artifacts link and when each was last reviewed |
+| [Framework README][framework-readme] | The framework this project uses |
+| [Framework changelog][framework-changelog] | What changed in each framework release |
+
+---
+
+[repository]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet
+[documentation]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet/wiki
+[wiki]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet/wiki
+[issues]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet/issues
+[screenshot-spell]: ./docs/images/spell-word.png
+[screenshot-retry]: ./docs/images/retry-invalid.png
+[agents]: ./AGENTS.md
+[BC-001]: ./docs/business-case.md
+[SA-001]: ./docs/stakeholder-analysis.md
+[PP-001]: ./docs/project-plan.md
+[milestones]: ./docs/milestones/
+[adr]: ./docs/adr/
+[ADR-0001]: ./docs/adr/adr-0001-read-nato-data-with-csv-module.md
+[registry]: ./docs/artifact-registry.md
+[TM-001]: ./docs/sqa/traceability-matrix.md
+[framework-readme]: ./framework/README.md
+[framework-changelog]: ./framework/CHANGELOG.md
@@ -15,7 +15,8 @@ document of a type. `Primary File` may contain a glob (e.g.
 | SA | Stakeholder Analysis | docs/stakeholder-analysis.md | 002 |
 | PP | Project Plan | docs/project-plan.md | 002 |
 | MIL | Milestone / Gateway | docs/milestones/*.md | 004 |
-| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 001 |
+| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 015 |
+| TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 |
 | ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0003 |
 | UCD | Use Case Diagram | docs/use-case-diagram.md | 002 |
 | US | User Story | docs/user-stories.md | 002 |
@@ -12,6 +12,7 @@
 | 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 | [80ec1bc] |
+| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Reviewed in RC-005 | [b69a604] |

 ---

@@ -74,3 +75,4 @@ The `README.md` built from the framework template with screenshots, and a wiki i
 [BC-001]: ../business-case.md
 [MIL-002]: ./mil-002-nato-converter.md
 [80ec1bc]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet/commit/80ec1bc3640e1aa2ad1f152b9f71df39fa71c2d1
+[b69a604]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet/commit/b69a604341251be410672cee93910e528eecaef8
@@ -0,0 +1,66 @@
+# SQA Review Record RC-005: MIL-003
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-005 |
+| CrossReference | [MIL-003], [QC-MIL-001], [QC-LANG-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Review of MIL-003 | [d367c2f] |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: [MIL-003]
+- Checklist used: [QC-MIL-001] and [QC-LANG-001]
+- Scope: full review
+- Language and domain: en / it
+- Language reviewer: none (the reviewer reads the language and knows the domain)
+- Mode: autonomous, not independent (the reviewer is `AI as stand-in for S01`)
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | A concrete deliverable is defined for every gate | Pass | Deliverable section names concrete output: README, screenshots and wiki in three languages. |
+| 2 | Explicit Go/No-Go criteria are stated for each gate | Pass | Go / No-Go table has objectively checkable rows (commands and counts). |
+| 3 | Dependencies on other milestones are explicitly mapped | Pass | Dependencies table is filled. |
+| 4 | Each milestone is traceable to a Business Case objective or KPI | Pass | Traceability cites [BC-001] objectives. |
+| 5 | Milestone owner and approving reviewer are identified | Pass | Owner and approving reviewer are S01. |
+| 6 | Milestone has a defined target date consistent with project constraints | Pass | Target date lies inside the Project Plan window; the Business Case sets no calendar constraint. |
+
+## Language and Domain Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | The Metadata table has a `Language` row and a `Domain` row, and neither is a placeholder | Pass | `Language | en` and `Domain | it` are in the Metadata table. |
+| 2 | `Language` is a BCP 47 code and `Domain` is a value from the registry's domain list | Pass | `en` is a BCP 47 code; `it` is in the registry's domain list. |
+| 3 | The content (prose and table cells) is written in the stated language | Pass | All prose and table cells are English; the course title is quoted source text. Checked by the stand-in reviewer, who reads English. |
+| 4 | The register matches the one the registry gives for the artifact type | Pass | The registry gives IT Executive English for this type; the text matches it. |
+| 5 | Domain terms are the PO terms of the domain's dictionary, with no synonyms | Pass | No dictionary (`DICT`) exists yet; the terms letter, code word and NATO alphabet are used consistently with no synonyms. Checked by the stand-in; open to challenge. |
+| 6 | Metadata keys, section headings, IDs and statuses are in English | Pass | Metadata keys, headings, IDs and statuses are English. |
+| 7 | No translated twin (`<name>.<language>.md`) exists beside the document | Pass | No translated twin of the file exists. |
+| 8 | A change of language or domain since the previous accepted version has a Version History row and was reviewed again | Pass | First version; no change of language or domain. |
+| 9 | A reviewer competent in the domain, and in the language, has confirmed that the domain terms are used correctly | Pass | The domain is software and IT and the language English; the reviewer stood in for (S01) reads both. A person may challenge this in the run summary. |
+| 10 | Abbreviations are spelled out on first use, in the stated language | Pass | Abbreviations are spelled out on first use or are identifiers (IDs, tool names). |
+
+## Overall Verdict
+
+Go — every Mandatory criterion of QC-MIL-001 and of QC-LANG-001 passes. Delivery evidence for the Go/No-Go criteria: `check-readme.sh` exits 0; the wiki pages Home, Install, Usage and Development exist in en, da and ms and answer HTTP 200 on the host, as does the screenshot; a fresh clone with a new `.venv` follows the README (`python -m pip install --upgrade pip`, `python -m pip install -e ".[dev]"`, `python -m pytest` 49 passed, the program run, `doxygen Doxyfile` with 0 warnings). The review is a stand-in review by the author's AI and is not independent; it is open to challenge in the run summary.
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| None | S01 | n/a |
+
+---
+
+[MIL-003]: ../../milestones/mil-003-documentation-and-publication.md
+[QC-MIL-001]: ../../../framework/qc/artifacts/qc-milestones-gateways.md
+[QC-LANG-001]: ../../../framework/qc/artifacts/qc-language-domain.md
+[d367c2f]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet/commit/d367c2f8814623a0ad2c7b5c4646c155a086c82d
@@ -0,0 +1,78 @@
+# Traceability Matrix
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | TM-001 |
+| CrossReference | [BC-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version, rows for RC-001 to RC-014 | [b69a604] |
+
+---
+
+## Purpose
+
+Tracks backward and forward links between artifact instances so that the cross-artifact traceability can be checked. A row is added or updated whenever an artifact instance is created or reviewed.
+
+## Traceability Table
+
+| Artifact Instance | Type | Language | Domain | Upstream (Backward Link) | Downstream (Forward Link) | Last Reviewed (RC-ID) |
+| --- | --- | --- | --- | --- | --- | --- |
+| [BC-001] | Business Case | en | it | - | [SA-001], [PP-001], [MIL-001], [MIL-002], [MIL-003] | [RC-001] |
+| [SA-001] | Stakeholder Analysis | en | it | [BC-001] | [PP-001] | [RC-002] |
+| [PP-001] | Project Plan | en | it | [BC-001], [SA-001] | [MIL-001], [MIL-002], [MIL-003] | - |
+| [MIL-001] | Milestone | en | it | [BC-001], [PP-001] | [MIL-002], [ADR-0001], [ADR-0002] | [RC-003] |
+| [MIL-002] | Milestone | en | it | [BC-001], [MIL-001] | [MIL-003], [US-001], [UC-001], [PY-002] | [RC-004] |
+| [MIL-003] | Milestone | en | it | [BC-001], [MIL-002] | - | [RC-005] |
+| [ADR-0001] | ADR | - | - | [BC-001], [SA-001] | [PY-001] | [RC-006] |
+| [ADR-0002] | ADR | - | - | [BC-001] | - | [RC-007] |
+| [WF-001] | CI workflow | - | - | [MIL-001] | - | [RC-008] |
+| [UCD-001] | Use Case Diagram | en | it | [SA-001], [BC-001] | [US-001], [UC-001] | [RC-010] |
+| [US-001] | User Story | en | it | [UCD-001], [MIL-002] | [UC-001] | [RC-011] |
+| [UC-001] | Use Case | en | it | [UCD-001], [US-001] | [SSD-001], [PY-002] | [RC-012] |
+| [SSD-001] | System Sequence Diagram | en | it | [UC-001] | [PY-002] | [RC-013] |
+| [PY-002] | Python source | - | - | [UC-001], [SSD-001], [ADR-0001] | - | [RC-014] |
+| [PY-001] | Python source | - | - | [ADR-0001], [MIL-001] | - | [RC-009] |
+
+## Coverage Notes
+
+- `-` in Upstream means foundational; in Downstream it means nothing is built on it yet; in Last Reviewed it means no review record exists.
+- PP-001 has no QC checklist yet; it is accepted by the Product Owner's stand-in.
+- WF-001 and PY-001 are labels for reviewed code instances (no artifact file).
+- PY-002 is the label of the reviewed converter code.
+
+---
+
+[BC-001]: ../business-case.md
+[MIL-001]: ../milestones/mil-001-repository-foundation.md
+[MIL-002]: ../milestones/mil-002-nato-converter.md
+[MIL-003]: ../milestones/mil-003-documentation-and-publication.md
+[PP-001]: ../project-plan.md
+[RC-001]: ./reviews/rc-001-business-case.md
+[RC-002]: ./reviews/rc-002-stakeholder-analysis.md
+[RC-003]: ./reviews/rc-003-mil-001.md
+[RC-004]: ./reviews/rc-004-mil-002.md
+[RC-005]: ./reviews/rc-005-mil-003.md
+[SA-001]: ../stakeholder-analysis.md
+[ADR-0001]: ../adr/adr-0001-read-nato-data-with-csv-module.md
+[ADR-0002]: ../adr/adr-0002-skip-analysis-artifacts.md
+[WF-001]: ../../.gitea/workflows/ci.yml
+[PY-001]: ../../src/nato_phonetic_alphabet/constants.py
+[RC-006]: ./reviews/rc-006-adr-0001.md
+[RC-007]: ./reviews/rc-007-adr-0002.md
+[RC-008]: ./reviews/rc-008-ci-workflow.md
+[RC-009]: ./reviews/rc-009-python-skeleton.md
+[UCD-001]: ../use-case-diagram.md
+[US-001]: ../user-stories.md
+[UC-001]: ../uc-001/uc.md
+[SSD-001]: ../uc-001/ssd.md
+[PY-002]: ../../src/nato_phonetic_alphabet/main.py
+[RC-010]: ./reviews/rc-010-ucd-001.md
+[RC-011]: ./reviews/rc-011-us-001.md
+[RC-012]: ./reviews/rc-012-uc-001.md
+[RC-013]: ./reviews/rc-013-ssd-001.md
+[RC-014]: ./reviews/rc-014-python-converter.md
+[b69a604]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet/commit/b69a604341251be410672cee93910e528eecaef8
@@ -0,0 +1,47 @@
+# Udvikling
+
+🌐 [English](Development) · **Dansk** · [Bahasa Melayu](Development-ms)
+
+Sæt projektet op først ([Installation](Install-da)). Udvidelsen `dev` installerer pytest, ruff, mypy og import-linter.
+
+## Kør testene
+
+```bash
+python -m pytest
+```
+
+## Kør de kontroller, CI kører
+
+```bash
+python -m ruff check .
+python -m mypy
+lint-imports
+```
+
+## Byg kildedokumentationen
+
+```bash
+doxygen Doxyfile
+```
+
+Åbn `build/html/index.html`. Installér Doxygen fra [doxygen.nl](https://www.doxygen.nl/) eller din pakkehåndtering.
+
+## Sådan virker exception handling
+
+`spell_word` (i `domain/spelling.py`) slår hvert bogstav op i ordbogen i en `try`-blok. Et tegn, der ikke findes i alfabetet, giver en `KeyError`, som `except`-blokken gør til en `InvalidWordError`. `generate_phonetic` (i `application/phonetic.py`) fanger fejlen, beder brugeren skrive kun bogstaver og spørger igen, indtil ordet er gyldigt.
+
+## Kodens opbygning
+
+| Mappe | Indhold |
+| --- | --- |
+| `src/nato_phonetic_alphabet/domain/` | Staveregelen, uden input og output |
+| `src/nato_phonetic_alphabet/application/` | Use casen og dens porte |
+| `src/nato_phonetic_alphabet/adapters/` | CSV-læseren og konsollen |
+| `src/nato_phonetic_alphabet/constants.py` | Alle programmets konstanter |
+| `tests/` | pytest-tests, som spejler `src/` |
+
+Afhængigheder peger indad: adapters kender applikationen, applikationen kender domænet. import-linter håndhæver det.
+
+## Pull requests
+
+Én gren og én pull request pr. milepæl; CI skal være grøn. Projektet følger SQA- og QC-frameworket i `framework/`; se `docs/` for planen og review-optegnelserne.
@@ -0,0 +1,47 @@
+# Pembangunan
+
+🌐 [English](Development) · [Dansk](Development-da) · **Bahasa Melayu**
+
+Sediakan projek dahulu ([Pemasangan](Install-ms)). Pilihan tambahan `dev` memasang pytest, ruff, mypy dan import-linter.
+
+## Jalankan ujian
+
+```bash
+python -m pytest
+```
+
+## Jalankan semakan yang dijalankan oleh CI
+
+```bash
+python -m ruff check .
+python -m mypy
+lint-imports
+```
+
+## Bina dokumentasi sumber
+
+```bash
+doxygen Doxyfile
+```
+
+Buka `build/html/index.html`. Pasang Doxygen dari [doxygen.nl](https://www.doxygen.nl/) atau pengurus pakej anda.
+
+## Cara pengendalian pengecualian berfungsi
+
+`spell_word` (dalam `domain/spelling.py`) mencari setiap huruf dalam kamus di dalam blok `try`. Aksara yang tiada dalam abjad menimbulkan `KeyError`, yang ditukar oleh blok `except` kepada `InvalidWordError`. `generate_phonetic` (dalam `application/phonetic.py`) menangkap ralat itu, meminta pengguna memasukkan huruf sahaja dan bertanya semula sehingga perkataan itu sah.
+
+## Susun atur kod
+
+| Folder | Kandungan |
+| --- | --- |
+| `src/nato_phonetic_alphabet/domain/` | Peraturan ejaan, tanpa input dan output |
+| `src/nato_phonetic_alphabet/application/` | Kes guna dan portnya |
+| `src/nato_phonetic_alphabet/adapters/` | Pembaca CSV dan konsol |
+| `src/nato_phonetic_alphabet/constants.py` | Semua pemalar program |
+| `tests/` | Ujian pytest, mencerminkan `src/` |
+
+Kebergantungan menghala ke dalam: adapter mengenali aplikasi, aplikasi mengenali domain. import-linter menguatkuasakannya.
+
+## Pull request
+
+Satu cabang dan satu pull request bagi setiap milestone; CI mesti hijau. Projek ini mengikut rangka kerja SQA dan QC dalam `framework/`; lihat `docs/` untuk pelan dan rekod semakan.
@@ -0,0 +1,47 @@
+# Development
+
+🌐 **English** · [Dansk](Development-da) · [Bahasa Melayu](Development-ms)
+
+Set up the project first ([Install](Install)). The `dev` extra installs pytest, ruff, mypy and import-linter.
+
+## Run the tests
+
+```bash
+python -m pytest
+```
+
+## Run the checks that CI runs
+
+```bash
+python -m ruff check .
+python -m mypy
+lint-imports
+```
+
+## Build the source documentation
+
+```bash
+doxygen Doxyfile
+```
+
+Open `build/html/index.html`. Install Doxygen from [doxygen.nl](https://www.doxygen.nl/) or your package manager.
+
+## How the exception handling works
+
+`spell_word` (in `domain/spelling.py`) looks every letter up in the dictionary inside a `try` block. A character that is not in the alphabet raises a `KeyError`, which the `except` block turns into an `InvalidWordError`. `generate_phonetic` (in `application/phonetic.py`) catches that error, tells the user to enter letters only and asks again until the word is valid.
+
+## Code layout
+
+| Folder | Content |
+| --- | --- |
+| `src/nato_phonetic_alphabet/domain/` | The spelling rule, with no input or output |
+| `src/nato_phonetic_alphabet/application/` | The use case and its ports |
+| `src/nato_phonetic_alphabet/adapters/` | The CSV reader and the console |
+| `src/nato_phonetic_alphabet/constants.py` | Every literal of the program |
+| `tests/` | pytest tests, mirroring `src/` |
+
+Dependencies point inward: adapters know the application, the application knows the domain. import-linter enforces it.
+
+## Pull requests
+
+One branch and one pull request per milestone; CI must be green. The project follows the SQA and QC framework in `framework/`; see `docs/` for the plan and the review records.
@@ -0,0 +1,23 @@
+# Det fonetiske NATO-alfabet
+
+🌐 [English](Home) · **Dansk** · [Bahasa Melayu](Home-ms)
+
+Et konsolprogram, der staver et ord med det fonetiske NATO-alfabet. Det er opgaven fra dag 30 i Udemys "100 Days of Code: The Complete Python Pro Bootcamp" og viser exception handling: input, der ikke er et bogstav, fanges med `try` og `except` i stedet for at få programmet til at gå ned. Det kræver Python 3.13 eller nyere og har ingen runtime-afhængigheder.
+
+![Programmet staver ordet Hello](images/spell-word.png)
+
+| Side | Læs den, når du vil |
+| --- | --- |
+| [Installation](Install-da) | Oprette et lokalt `.venv` og installere projektet på Windows, Linux eller macOS |
+| [Brug](Usage-da) | Køre programmet og læse dets output |
+| [Udvikling](Development-da) | Køre testene og kontrollerne og bygge kildedokumentationen |
+
+## Hvem det er til
+
+- **Kursister**, der vil have en læsbar løsning med opgavens funktionsnavne (`load_nato_dict`, `generate_phonetic`) at sammenligne med deres egen.
+- **GitHub-besøgende**, der vil se et lille, testet Python-projekt uden runtime-afhængigheder.
+
+## Links
+
+- [Repository](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet)
+- [Fejl og ønsker](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet/issues)
@@ -0,0 +1,23 @@
+# Abjad fonetik NATO
+
+🌐 [English](Home) · [Dansk](Home-da) · **Bahasa Melayu**
+
+Alat konsol yang mengeja satu perkataan dengan abjad fonetik NATO. Ia ialah tugasan hari ke-30 dalam "100 Days of Code: The Complete Python Pro Bootcamp" di Udemy dan menunjukkan pengendalian pengecualian (exception handling): input yang bukan huruf ditangkap dengan `try` dan `except` dan bukannya menyebabkan program terhenti. Ia memerlukan Python 3.13 atau lebih baharu dan tidak mempunyai kebergantungan masa jalan.
+
+![Alat mengeja perkataan Hello](images/spell-word.png)
+
+| Halaman | Baca apabila anda mahu |
+| --- | --- |
+| [Pemasangan](Install-ms) | Mencipta `.venv` setempat dan memasang projek di Windows, Linux atau macOS |
+| [Penggunaan](Usage-ms) | Menjalankan program dan membaca outputnya |
+| [Pembangunan](Development-ms) | Menjalankan ujian dan semakan serta membina dokumentasi sumber |
+
+## Untuk siapa
+
+- **Peserta kursus** yang mahukan penyelesaian yang mudah dibaca dengan nama fungsi tugasan (`load_nato_dict`, `generate_phonetic`) untuk dibandingkan dengan penyelesaian sendiri.
+- **Pelawat GitHub** yang mahukan projek Python kecil yang diuji tanpa kebergantungan masa jalan.
+
+## Pautan
+
+- [Repositori](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet)
+- [Penjejak isu](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet/issues)
@@ -0,0 +1,23 @@
+# NATO phonetic alphabet
+
+🌐 **English** · [Dansk](Home-da) · [Bahasa Melayu](Home-ms)
+
+A console tool that spells a word with the NATO phonetic alphabet. It is the Day 30 assignment of Udemy's "100 Days of Code: The Complete Python Pro Bootcamp" and shows exception handling: input that is not a letter is caught with `try` and `except` instead of crashing the program. It needs Python 3.13 or newer and has no runtime dependencies.
+
+![The tool spelling the word Hello](images/spell-word.png)
+
+| Page | Read it when you want to |
+| --- | --- |
+| [Install](Install) | Create a local `.venv` and install the project on Windows, Linux or macOS |
+| [Usage](Usage) | Run the program and read its output |
+| [Development](Development) | Run the tests, the checks and build the source documentation |
+
+## Who it is for
+
+- **Course participants** who want a readable solution with the assignment's function names (`load_nato_dict`, `generate_phonetic`) to compare with their own.
+- **GitHub viewers** who want a small, tested Python project with no runtime dependencies.
+
+## Links
+
+- [Repository](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet)
+- [Issue tracker](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet/issues)
@@ -0,0 +1,57 @@
+# Installation
+
+🌐 [English](Install) · **Dansk** · [Bahasa Melayu](Install-ms)
+
+## Det skal du bruge
+
+- Python 3.13 eller nyere med modulet `venv`
+- Git
+
+## Trin
+
+Alle systemer gør de samme fire ting: klon repository'et, opret et virtuelt miljø kaldet `.venv`, opgradér pip og installér projektet.
+
+### Windows PowerShell
+
+```powershell
+git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet.git
+cd 030-nato-phonetic-alphabet
+py -3.13 -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+Hvis PowerShell afviser aktiveringsscriptet, så kør først `Set-ExecutionPolicy -Scope Process RemoteSigned`. Det gælder kun for det vindue.
+
+### Linux Debian
+
+```bash
+sudo apt install git python3 python3-venv
+git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet.git
+cd 030-nato-phonetic-alphabet
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+### macOS
+
+```bash
+brew install python@3.13 git
+git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet.git
+cd 030-nato-phonetic-alphabet
+python3.13 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+## Tjek at det virker
+
+```bash
+python -m nato_phonetic_alphabet
+```
+
+Skriv et ord. Du skal se dets kodeord. Næste side: [Brug](Usage-da).
@@ -0,0 +1,57 @@
+# Pemasangan
+
+🌐 [English](Install) · [Dansk](Install-da) · **Bahasa Melayu**
+
+## Apa yang diperlukan
+
+- Python 3.13 atau lebih baharu dengan modul `venv`
+- Git
+
+## Langkah
+
+Semua sistem melakukan empat perkara yang sama: klon repositori, cipta persekitaran maya bernama `.venv`, naik taraf pip dan pasang projek.
+
+### Windows PowerShell
+
+```powershell
+git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet.git
+cd 030-nato-phonetic-alphabet
+py -3.13 -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+Jika PowerShell enggan menjalankan skrip pengaktifan, jalankan `Set-ExecutionPolicy -Scope Process RemoteSigned` dahulu. Ia hanya terpakai pada tetingkap itu.
+
+### Linux Debian
+
+```bash
+sudo apt install git python3 python3-venv
+git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet.git
+cd 030-nato-phonetic-alphabet
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+### macOS
+
+```bash
+brew install python@3.13 git
+git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet.git
+cd 030-nato-phonetic-alphabet
+python3.13 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+## Semak ia berfungsi
+
+```bash
+python -m nato_phonetic_alphabet
+```
+
+Masukkan satu perkataan. Anda akan melihat kata kodnya. Seterusnya: [Penggunaan](Usage-ms).
@@ -0,0 +1,57 @@
+# Install
+
+🌐 **English** · [Dansk](Install-da) · [Bahasa Melayu](Install-ms)
+
+## What you need
+
+- Python 3.13 or newer with the `venv` module
+- Git
+
+## Steps
+
+Every system does the same four things: clone the repository, create a virtual environment called `.venv`, upgrade pip, install the project.
+
+### Windows PowerShell
+
+```powershell
+git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet.git
+cd 030-nato-phonetic-alphabet
+py -3.13 -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+If PowerShell refuses to run the activation script, run `Set-ExecutionPolicy -Scope Process RemoteSigned` first. It only applies to that window.
+
+### Linux Debian
+
+```bash
+sudo apt install git python3 python3-venv
+git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet.git
+cd 030-nato-phonetic-alphabet
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+### macOS
+
+```bash
+brew install python@3.13 git
+git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet.git
+cd 030-nato-phonetic-alphabet
+python3.13 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+## Check that it works
+
+```bash
+python -m nato_phonetic_alphabet
+```
+
+Enter a word. You should see its code words. Next: [Usage](Usage).
@@ -0,0 +1,31 @@
+# Brug
+
+🌐 [English](Usage) · **Dansk** · [Bahasa Melayu](Usage-ms)
+
+Aktivér det virtuelle miljø (se [Installation](Install-da)), og start programmet:
+
+```bash
+python -m nato_phonetic_alphabet
+```
+
+Den installerede kommando gør det samme:
+
+```bash
+nato-phonetic-alphabet
+```
+
+## Stav et ord
+
+Programmet spørger efter et ord og skriver NATO-kodeordet for hvert bogstav i rækkefølge. Store og små bogstaver giver samme resultat.
+
+![Programmet staver ordet Hello](images/spell-word.png)
+
+## Ugyldigt input
+
+Et ciffer, et mellemrum eller et tegn er ikke et bogstav. Programmet siger det og spørger igen.
+
+![Et ord med et ciffer afvises, derefter staves et gyldigt ord](images/retry-invalid.png)
+
+## Tryk Ctrl+C eller Ctrl+D
+
+Afslutter du inputtet (Ctrl+D på Linux og macOS, Ctrl+Z og Enter på Windows) eller trykker Ctrl+C, lukker programmet stille.
@@ -0,0 +1,31 @@
+# Penggunaan
+
+🌐 [English](Usage) · [Dansk](Usage-da) · **Bahasa Melayu**
+
+Aktifkan persekitaran maya (lihat [Pemasangan](Install-ms)), kemudian mulakan program:
+
+```bash
+python -m nato_phonetic_alphabet
+```
+
+Arahan yang dipasang melakukan perkara yang sama:
+
+```bash
+nato-phonetic-alphabet
+```
+
+## Eja satu perkataan
+
+Program meminta satu perkataan dan mencetak kata kod NATO bagi setiap huruf mengikut urutan. Huruf besar dan huruf kecil memberi keputusan yang sama.
+
+![Alat mengeja perkataan Hello](images/spell-word.png)
+
+## Input tidak sah
+
+Angka, ruang atau tanda baca bukan huruf. Program memberitahu perkara itu dan bertanya semula.
+
+![Perkataan dengan angka ditolak, kemudian perkataan yang sah dieja](images/retry-invalid.png)
+
+## Tekan Ctrl+C atau Ctrl+D
+
+Menamatkan input (Ctrl+D di Linux dan macOS, Ctrl+Z kemudian Enter di Windows) atau menekan Ctrl+C menutup program dengan senyap.
@@ -0,0 +1,31 @@
+# Usage
+
+🌐 **English** · [Dansk](Usage-da) · [Bahasa Melayu](Usage-ms)
+
+Activate the virtual environment (see [Install](Install)), then start the program:
+
+```bash
+python -m nato_phonetic_alphabet
+```
+
+The installed command does the same:
+
+```bash
+nato-phonetic-alphabet
+```
+
+## Spell a word
+
+The program asks for a word and prints the NATO code word of each letter, in order. Upper and lower case give the same result.
+
+![The tool spelling the word Hello](images/spell-word.png)
+
+## Invalid input
+
+A digit, a space or a punctuation mark is not a letter. The program says so and asks again.
+
+![A word with a digit is rejected, then a valid word is spelled](images/retry-invalid.png)
+
+## Press Ctrl+C or Ctrl+D
+
+Ending the input (Ctrl+D on Linux and macOS, Ctrl+Z then Enter on Windows) or pressing Ctrl+C closes the program quietly.
@@ -0,0 +1,24 @@
+**NATO phonetic alphabet**
+
+- [Home](Home)
+- [Install](Install)
+- [Usage](Usage)
+- [Development](Development)
+
+**Dansk**
+
+- [Hjem](Home-da)
+- [Installation](Install-da)
+- [Brug](Usage-da)
+- [Udvikling](Development-da)
+
+**Bahasa Melayu**
+
+- [Utama](Home-ms)
+- [Pemasangan](Install-ms)
+- [Penggunaan](Usage-ms)
+- [Pembangunan](Development-ms)
+
+**Links**
+
+- [Repository](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet)
Author	SHA1	Message	Date
Tirsvad	3150fc4755	Merge pull request 'MIL-003 Documentation and publication' (#22 ) from mil-003-documentation-and-publication into main TirSystem/github-action: Sync GitHub mirror metadata / sync-metadata (push) Successful in 9s Details Merge pull request MIL-003 Documentation and publication (#22)	2026-10-14 13:40:58 +02:00
Tirsvad	c53cb3fb4a	Resolve pending commit links for MIL-003 Refs #13	2026-10-14 19:40:08 +08:00
Tirsvad	d367c2f881	Record the MIL-003 delivery evidence in RC-005 Refs #19	2026-10-14 19:40:06 +08:00
Tirsvad	b69a604341	MIL-003 Documentation and publication: README, screenshots and wiki in en, da and ms Task: MIL-003#1 Task: MIL-003#2 Task: MIL-003#3 Task: MIL-003#4 Task: MIL-003#5 Task: MIL-003#6	2026-10-14 19:38:55 +08:00
Tirsvad	44c1e69fb3	Merge pull request 'MIL-002 NATO converter' (#21 ) from mil-002-nato-converter into main CI / Test on Python 3.13 (push) Successful in 58s Details TirSystem/github-action: Sync GitHub mirror metadata / sync-metadata (push) Successful in 7s Details Merge pull request MIL-002 NATO converter (#21)	2026-10-14 13:36:39 +02:00