Lerking/python-MIT-repo-template
1
0
Fork 0
generated from Lerking/python-repo-template
Code Issues Pull Requests Packages Projects Releases 1 Wiki Activity

0.1.0 #1

Merged
Lerking merged 8 commits from 0.1.0 into main 2026-08-26 12:46:04 +02:00
Conversation 0 Commits 8 Files Changed 10
+416 -1
10 changed files with 416 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+17 -1
View File
@@ -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.
docs/NEW_PROJECT_CHECKLIST.md
+64
View File
@@ -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
- [ ]
- [ ]
docs/PROJECT_SPECIFICATION_TEMPLATE.md
+155
View File
@@ -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 |
docs/value-stream-mapping/value_stream_map_template.odp
BIN
View File
Binary file not shown.
wiki/Architecture.md
+35
View File
@@ -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 |
|---|---|---|
| | | |
wiki/FAQ.md
+10
View File
@@ -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>`
wiki/Getting-Started.md
+37
View File
@@ -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 |
|---|---|---|
| | | |
wiki/Home.md
+33
View File
@@ -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>`
wiki/Project-Specification.md
+28
View File
@@ -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
wiki/Value-Stream-Mapping.md
+37
View File
@@ -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 |
|---|---|---|---|
| | | | |