From 60cf3e26e03189abbebeafb471ea148758118123 Mon Sep 17 00:00:00 2001 From: Lerking <1+lerking@noreply.localhost> Date: Wed, 26 Aug 2026 12:36:46 +0200 Subject: [PATCH] Upload files to "docs" --- docs/NEW_PROJECT_CHECKLIST.md | 64 ++++++++++ docs/PROJECT_SPECIFICATION_TEMPLATE.md | 155 +++++++++++++++++++++++++ 2 files changed, 219 insertions(+) create mode 100644 docs/NEW_PROJECT_CHECKLIST.md create mode 100644 docs/PROJECT_SPECIFICATION_TEMPLATE.md 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 |