2026-08-26 12:46:04 +02:00
10 changed files with 416 additions and 1 deletions
@@ -27,4 +27,20 @@ See the wiki for usage and examples.
 [python-repo-template wiki page](https://github.com/Lerking/python-repo-template/wiki)
 Visitors since repo creation.</br>
-![Visitor Badge](https://visitor-badge.laobi.icu/badge?page_id=Lerking.python-repo-template)
+![Visitor Badge](https://visitor-badge.laobi.icu/badge?page_id=Lerking.python-repo-template)
 ## Using this as a project template
 Beyond the bare Python repo scaffold (`main.py`, `LICENCE`, `.gitignore`), this template
 includes everything needed to kick off a new project properly:
 | What | Where |
 |---|---|
 | Project specification template | [`docs/PROJECT_SPECIFICATION_TEMPLATE.md`](docs/PROJECT_SPECIFICATION_TEMPLATE.md) |
 | Value stream mapping template (OpenDocument Presentation) | [`docs/value-stream-mapping/value_stream_map_template.odp`](docs/value-stream-mapping/value_stream_map_template.odp) |
 | New project setup checklist | [`docs/NEW_PROJECT_CHECKLIST.md`](docs/NEW_PROJECT_CHECKLIST.md) |
 | Wiki template (copy into your repo's actual wiki) | [`wiki/`](wiki/) |
 | Standard first-step issues (value stream goals, specification, wiki setup, checklist) | [`.github/ISSUE_TEMPLATE/`](.github/ISSUE_TEMPLATE/) |
 Start with the checklist — it walks through repository setup, defining the project (value
 stream map + specification), planning, tooling, documentation, and kickoff, in order.
@@ -0,0 +1,64 @@
 # New Project Checklist
 Work through this checklist when setting up a new project from this template. It's ordered
 roughly in the sequence you'd actually do the work, but feel free to skip items that don't
 apply and add project-specific ones at the bottom.
 ## 1. Repository setup
 - [ ] Create the repository from this template
 - [ ] Rename the project (repo name, `main.py` header, README title)
 - [ ] Update `LICENCE` copyright holder and year
 - [ ] Review `.gitignore` for anything project-specific to add (env files, build artefacts, data dumps)
 - [ ] Set repository visibility (public/private) and default branch protections
 - [ ] Add collaborators / team access
 - [ ] Update README badges (or remove the ones that don't apply)
 - [ ] Enable the wiki and publish the [wiki template](../wiki/Home.md) pages
 ## 2. Define the project
 - [ ] Create the [Value Stream Map](value-stream-mapping/value_stream_map_template.odp) —
      current state at minimum, future state if the target process is already known
 - [ ] Open the **"Define value stream goals"** issue (from the issue templates) and fill it in
 - [ ] Open the **"Write project specification"** issue and complete the
      [project specification template](PROJECT_SPECIFICATION_TEMPLATE.md)
 - [ ] Get the specification reviewed and approved by stakeholders
 - [ ] Identify and record non-goals explicitly — don't skip this
 ## 3. Planning
 - [ ] Break the specification down into milestones
 - [ ] Create the standard setup issues (see `.github/ISSUE_TEMPLATE/`) in the issue tracker
 - [ ] Set up a project board / backlog and add the initial issues to it
 - [ ] Agree on a definition of "done" for issues and for the project as a whole
 - [ ] Identify risks and mitigations (Section 12 of the specification)
 ## 4. Environment & tooling
 - [ ] Choose and pin the Python version (`.python-version` / `pyproject.toml`)
 - [ ] Set up the virtual environment / dependency manager
 - [ ] Add linting and formatting tools and their configuration
 - [ ] Add a test framework and a first smoke test
 - [ ] Set up CI (lint, test, build) on push/PR
 - [ ] Configure branch protection to require CI + review before merge
 ## 5. Documentation
 - [ ] Fill in the README with an actual project description, setup, and usage instructions
 - [ ] Link the project specification and value stream map from the README
 - [ ] Set up the wiki structure (see `wiki/`) with at least a Home page and a
      Getting Started page
 - [ ] Document how to run, test, and deploy the project
 ## 6. Kickoff
 - [ ] Walk stakeholders through the approved specification and value stream map
 - [ ] Confirm milestones and timeline with everyone involved
 - [ ] Close out the setup issues once each is genuinely complete — don't just close them to
      clear the board
 - [ ] Schedule the first review checkpoint (e.g. after MVP / first milestone)
 ## Project-specific additions
 - [ ]
 - [ ]
@@ -0,0 +1,155 @@
 # Project Specification: <Project Name>
 > **How to use this template:** Copy this file to `docs/PROJECT_SPECIFICATION.md` in your new
 > project, then work through it top to bottom. Every `<placeholder>` should be replaced or
 > removed. Sections marked *(optional)* can be deleted if they genuinely don't apply — don't
 > delete them just because they're hard to answer. Keep this document updated as the project
 > evolves; it is the single source of truth for what the project is and why.
 | | |
 |---|---|
 | **Status** | Draft / In Review / Approved |
 | **Owner** | <name> |
 | **Created** | <yyyy-mm-dd> |
 | **Last updated** | <yyyy-mm-dd> |
 | **Version** | 0.1 |
 ---
 ## 1. Summary
 A short (3–5 sentence) description of the project, written so that someone outside the
 project can understand what it is and why it exists without reading further.
 ## 2. Problem Statement
 - What problem are we solving?
 - Who has this problem, and how do they experience it today?
 - What happens if we do nothing?
 ## 3. Goals
 Concrete, testable statements of what success looks like. Prefer measurable outcomes over
 vague aspirations.
 - [ ] Goal 1
 - [ ] Goal 2
 - [ ] Goal 3
 ## 4. Non-Goals
 Explicitly out of scope. This section prevents scope creep and mismatched expectations —
 it is as important as the goals section.
 - Non-goal 1
 - Non-goal 2
 ## 5. Stakeholders
 | Role | Name | Interest / Responsibility |
 |---|---|---|
 | Sponsor | | |
 | Product owner | | |
 | Tech lead | | |
 | End users | | |
 | Other | | |
 ## 6. Background & Context *(optional)*
 Relevant history, prior attempts, related systems, or decisions that shape this project.
 Link to the [Value Stream Map](../docs/value-stream-mapping/) if one has been produced —
 it often surfaces the problem this project addresses.
 ## 7. Scope
 ### 7.1 In Scope
 - Item 1
 - Item 2
 ### 7.2 Out of Scope
 - Item 1
 - Item 2
 ## 8. Requirements
 ### 8.1 Functional Requirements
 | ID | Requirement | Priority (Must/Should/Could/Won't) |
 |---|---|---|
 | FR-1 | | Must |
 | FR-2 | | Should |
 ### 8.2 Non-Functional Requirements
 Consider at least: performance, scalability, security, privacy, accessibility,
 reliability/availability, maintainability, observability, compliance.
 | ID | Requirement | Notes |
 |---|---|---|
 | NFR-1 | | |
 | NFR-2 | | |
 ## 9. Users & Use Cases *(optional)*
 Describe the primary user(s)/persona(s) and the key use cases or user stories.
 - As a `<user type>`, I want to `<action>`, so that `<benefit>`.
 ## 10. Architecture & Design
 - High-level architecture (diagram, or link to one).
 - Key components and their responsibilities.
 - Technology choices and why they were made.
 - Data model / schema, if applicable.
 - External interfaces / APIs / integrations.
 ## 11. Constraints & Assumptions
 | Type | Description |
 |---|---|
 | Constraint | e.g. must run on existing infrastructure, fixed deadline, budget cap |
 | Assumption | e.g. third-party API will remain stable, expected data volume |
 ## 12. Risks
 | Risk | Likelihood | Impact | Mitigation |
 |---|---|---|---|
 | | Low/Med/High | Low/Med/High | |
 ## 13. Milestones & Timeline
 | Milestone | Target date | Notes |
 |---|---|---|
 | Project kickoff | | |
 | Specification approved | | |
 | MVP / first working version | | |
 | Release | | |
 ## 14. Success Metrics / Acceptance Criteria
 How will we know the project succeeded? Prefer measurable, falsifiable criteria over
 "it works."
 - [ ] Criterion 1
 - [ ] Criterion 2
 ## 15. Open Questions
 Track unresolved questions here so they don't get lost. Move resolved items to a decision
 log or into the relevant section above.
 | Question | Owner | Status |
 |---|---|---|
 | | | Open |
 ## 16. Glossary *(optional)*
 | Term | Definition |
 |---|---|
 | | |
 ## 17. Revision History
 | Version | Date | Author | Summary of changes |
 |---|---|---|---|
 | 0.1 | <yyyy-mm-dd> | | Initial draft |
@@ -0,0 +1,35 @@
 # Architecture
 > Keep this page in sync with the "Architecture & Design" section of the project
 > specification. The specification captures the *decision*; this page captures the
 > *current, evolving state* of the system for people working in the codebase day to day.
 ## Overview
 One paragraph: what the major pieces are and how they fit together. Include or link a
 diagram.
 ## Components
 | Component | Responsibility | Depends on |
 |---|---|---|
 | | | |
 ## Data flow
 Describe how data moves through the system, from input to output.
 ## External dependencies
 | Dependency | Purpose | Notes |
 |---|---|---|
 | | | |
 ## Key design decisions
 A short log of significant decisions and the reasoning behind them (an ADR-style list is
 fine here if you don't have a separate `docs/adr/` folder).
 | Decision | Date | Reasoning |
 |---|---|---|
 | | | |
@@ -0,0 +1,10 @@
 # FAQ
 > A running list of questions that came up more than once. If you find yourself answering
 > the same question in an issue or chat, add it here.
 **Q: `<question>`**
 A: `<answer>`
 **Q: `<question>`**
 A: `<answer>`
@@ -0,0 +1,37 @@
 # Getting Started
 ## Prerequisites
 - Python `<version>`
 - `<other tools: e.g. Docker, make, poetry>`
 ## Installation
 ```bash
 git clone <repo-url>
 cd <project>
 <install command, e.g. pip install -r requirements.txt>
 ```
 ## Configuration
 - Environment variables / config file(s) needed, and where to get their values
 - Any secrets or credentials required, and how to obtain them safely (never commit them)
 ## Running the project
 ```bash
 <run command>
 ```
 ## Running the tests
 ```bash
 <test command>
 ```
 ## Common issues
 | Symptom | Cause | Fix |
 |---|---|---|
 | | | |
@@ -0,0 +1,33 @@
 # <Project Name> Wiki
 > Copy the pages in this `wiki/` folder into your repository's actual GitHub Wiki (or your
 > wiki tool of choice), then fill them in. File names map to page titles, so keep them as-is
 > unless you're renaming the page. Delete this note once the wiki is populated.
 Welcome. This wiki is the living documentation for the project — the specification and value
 stream map describe what we set out to build and why; this wiki describes how the project
 actually works and how to use it, day to day.
 ## Pages
 - **[[Getting Started]]** — install, configure, and run the project locally
 - **[[Architecture]]** — how the system is put together and why
 - **[[Project Specification]]** — link/summary of the approved specification
 - **[[Value Stream Mapping]]** — link/summary of the current & future state maps
 - **[[FAQ]]** — common questions and troubleshooting
 ## Quick links
 | | |
 |---|---|
 | Repository | `<link>` |
 | Issue tracker | `<link>` |
 | Project specification | [docs/PROJECT_SPECIFICATION.md](../docs/PROJECT_SPECIFICATION_TEMPLATE.md) |
 | Value stream map | [docs/value-stream-mapping/](../docs/value-stream-mapping/) |
 | CI / build status | `<link>` |
 ## Conventions
 - Branching model: `<e.g. trunk-based, git-flow>`
 - Commit message style: `<e.g. Conventional Commits>`
 - Where decisions get recorded: `<e.g. ADRs in docs/adr/, this wiki, issue comments>`
@@ -0,0 +1,28 @@
 # Project Specification
 The authoritative project specification lives in
 [`docs/PROJECT_SPECIFICATION.md`](../docs/PROJECT_SPECIFICATION_TEMPLATE.md) (based on the
 [project specification template](../docs/PROJECT_SPECIFICATION_TEMPLATE.md)), not on this
 wiki page — it needs version control and review history that the wiki doesn't give you.
 This page exists so the specification is easy to find. Keep it updated with:
 - **Current version:** `<version>`
 - **Status:** Draft / In Review / Approved
 - **Last approved:** `<date>`
 ## Summary
 Paste the 3–5 sentence summary from Section 1 of the specification here, so readers get the
 gist without leaving the wiki.
 ## Key goals
 - Goal 1
 - Goal 2
 - Goal 3
 ## Notable non-goals
 - Non-goal 1
 - Non-goal 2
@@ -0,0 +1,37 @@
 # Value Stream Mapping
 The current and future state value stream maps live in
 [`docs/value-stream-mapping/`](../docs/value-stream-mapping/) as an OpenDocument
 Presentation (`.odp`), editable in LibreOffice Impress, OpenOffice Impress, or (with
 conversion) PowerPoint/Google Slides.
 ## Current state summary
 Briefly describe the current process, its main bottlenecks, and the headline metrics
 (total lead time, total cycle time, %C&A) once the current state map is complete.
 | Metric | Value |
 |---|---|
 | Total lead time | |
 | Total cycle time (value-added time) | |
 | Process cycle efficiency | |
 ## Future state summary
 Briefly describe the target process and what changes once the future state map is
 complete.
 | Metric | Value |
 |---|---|
 | Target lead time | |
 | Target cycle time | |
 | Target process cycle efficiency | |
 ## Improvement actions
 Pulled from the action plan slide in the map — kept here for visibility, updated from the
 `.odp` file when it changes.
 | Action | Owner | Due | Status |
 |---|---|---|---|
 | | | | |