diff --git a/README.md b/README.md index b6f8604..f673f9d 100644 --- a/README.md +++ b/README.md @@ -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.
-![Visitor Badge](https://visitor-badge.laobi.icu/badge?page_id=Lerking.python-repo-template) \ No newline at end of file +![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. diff --git a/docs/NEW_PROJECT_CHECKLIST.md b/docs/NEW_PROJECT_CHECKLIST.md new file mode 100644 index 0000000..f7a9dc1 --- /dev/null +++ b/docs/NEW_PROJECT_CHECKLIST.md @@ -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 + +- [ ] +- [ ] diff --git a/docs/PROJECT_SPECIFICATION_TEMPLATE.md b/docs/PROJECT_SPECIFICATION_TEMPLATE.md new file mode 100644 index 0000000..b5da66d --- /dev/null +++ b/docs/PROJECT_SPECIFICATION_TEMPLATE.md @@ -0,0 +1,155 @@ +# Project Specification: + +> **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 `` 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** | | +| **Created** | | +| **Last updated** | | +| **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 ``, I want to ``, so that ``. + +## 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 | | | Initial draft | diff --git a/docs/value-stream-mapping/value_stream_map_template.odp b/docs/value-stream-mapping/value_stream_map_template.odp new file mode 100644 index 0000000..4a73e92 Binary files /dev/null and b/docs/value-stream-mapping/value_stream_map_template.odp differ diff --git a/wiki/Architecture.md b/wiki/Architecture.md new file mode 100644 index 0000000..493bd12 --- /dev/null +++ b/wiki/Architecture.md @@ -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 | +|---|---|---| +| | | | diff --git a/wiki/FAQ.md b/wiki/FAQ.md new file mode 100644 index 0000000..abf9b56 --- /dev/null +++ b/wiki/FAQ.md @@ -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: ``** +A: `` + +**Q: ``** +A: `` diff --git a/wiki/Getting-Started.md b/wiki/Getting-Started.md new file mode 100644 index 0000000..f4e1765 --- /dev/null +++ b/wiki/Getting-Started.md @@ -0,0 +1,37 @@ +# Getting Started + +## Prerequisites + +- Python `` +- `` + +## Installation + +```bash +git clone +cd + +``` + +## 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 + +``` + +## Running the tests + +```bash + +``` + +## Common issues + +| Symptom | Cause | Fix | +|---|---|---| +| | | | diff --git a/wiki/Home.md b/wiki/Home.md new file mode 100644 index 0000000..6973885 --- /dev/null +++ b/wiki/Home.md @@ -0,0 +1,33 @@ +# 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 | `` | +| Issue tracker | `` | +| 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 | `` | + +## Conventions + +- Branching model: `` +- Commit message style: `` +- Where decisions get recorded: `` diff --git a/wiki/Project-Specification.md b/wiki/Project-Specification.md new file mode 100644 index 0000000..fb0c529 --- /dev/null +++ b/wiki/Project-Specification.md @@ -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:** `` +- **Status:** Draft / In Review / Approved +- **Last approved:** `` + +## 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 diff --git a/wiki/Value-Stream-Mapping.md b/wiki/Value-Stream-Mapping.md new file mode 100644 index 0000000..544a744 --- /dev/null +++ b/wiki/Value-Stream-Mapping.md @@ -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 | +|---|---|---|---| +| | | | |