Add context manifest and reference documentation

- ContextManifest.md: URLs for recreating external context dependencies - KeepaContributingfile.md: Keep a Contributing-File V0.0.1 format reference - KeepaTodofile.md: Keep a Todofile V0.0.1 format reference - PythonVibes.md: Python project best practices reference These files preserve the external documentation standards used throughout the project for reproducible context and consistent agent behavior. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-19 02:10:13 +02:00
parent 8f5c0a7cc6
commit cf45bea63b
4 changed files with 609 additions and 0 deletions
--- a/context/PythonVibes.md
+++ b/context/PythonVibes.md
@@ -0,0 +1,281 @@
+PythonVibes is a repository template to build vibe coding projects from. 
+It roughly follows the following best practices for organizing python repositories.
+
+# Python Project Repository Best Practice Guide
+
+> **Purpose**  
+> This guide defines the best practices for structuring, documenting, and maintaining Python repositories.  
+> It is based on official Python standards (PEPs) and widely adopted community conventions.
+
+---
+
+## 1. Version Control as a Foundation
+
+**Use Git for all projects.**
+
+### Key Practices
+- Initialize every project with Git (`git init` or `gh repo create`).
+- Commit logical units of work with meaningful messages.
+- Exclude irrelevant files using a `.gitignore` (e.g., from [GitHub’s Python.gitignore](https://github.com/github/gitignore)).
+- Use [Semantic Versioning](https://semver.org/) for tagging releases.
+
+**Reference:**  
+- [PEP 440 – Version Identification and Dependency Specification](https://peps.python.org/pep-0440/)
+
+**Rationale:**  
+Version control ensures traceability, collaboration, and reproducibility — the foundation for CI/CD and team workflows.
+
+---
+
+## 2. Environment Isolation
+
+**Always develop inside a virtual environment.**
+
+### Recommended Tools
+- Standard library: `python -m venv .venv`
+- Modern environment managers: [Poetry](https://python-poetry.org/), [PDM](https://pdm.fming.dev/), [Conda](https://docs.conda.io/)
+
+**Rationale:**  
+Virtual environments prevent dependency conflicts and ensure consistent behavior across systems.
+
+**Reference:**  
+- [Python Packaging User Guide – Creating and Using Virtual Environments](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/)
+
+---
+
+## 3. Dependency Management and Locking
+
+**Explicitly declare and lock dependencies.**
+
+### Options
+- `pyproject.toml` (modern, [PEP 621](https://peps.python.org/pep-0621/))
+- `requirements.txt` (legacy but widely supported)
+- `Pipfile` / `Pipfile.lock` (for Pipenv)
+
+**Rationale:**  
+Explicit dependency declaration ensures anyone can reproduce the project environment exactly.
+
+**Example:**  
+```bash
+pip install --no-cache-dir -r requirements.txt
+```
+
+---
+
+## 4. Recommended Directory Layout
+
+**Follow a clear, standardized project structure.**
+
+```
+project-name/
+├── src/
+│   └── project_name/
+│       ├── __init__.py
+│       ├── core.py
+│       └── utils.py
+├── tests/
+│   ├── __init__.py
+│   └── test_core.py
+├── docs/
+├── .github/
+│   └── workflows/
+├── .gitignore
+├── LICENSE
+├── pyproject.toml
+├── README.md
+└── requirements.txt
+```
+
+**Reference:**  
+- [The Hitchhiker’s Guide to Python – Structuring Your Project](https://docs.python-guide.org/writing/structure/)
+
+---
+
+## 5. Essential Repository Files
+
+| File | Purpose |
+|------|----------|
+| `README.md` | Overview, installation, usage, and examples |
+| `LICENSE` | Defines distribution and usage rights |
+| `.gitignore` | Prevents committing build and environment artifacts |
+| `pyproject.toml` | Declares project metadata and dependencies |
+| `CHANGELOG.md` | Documents version history ([Keep a Changelog](https://keepachangelog.com/en/1.1.0/)) |
+| `CONTRIBUTING.md` | Provides guidelines for contributors |
+
+**Optional:**
+- `CODE_OF_CONDUCT.md` — defines community expectations  
+- `Makefile` — simplifies common commands  
+- `.env.example` — documents environment variables  
+
+**Reference:**  
+- [PEP 518 – pyproject.toml Build System Configuration](https://peps.python.org/pep-0518/)
+
+---
+
+## 6. Testing and Quality Assurance
+
+**Automate tests and integrate them early.**
+
+### Best Practices
+- Use [pytest](https://docs.pytest.org/) for tests and fixtures.
+- Maintain a `tests/` directory at the root of the repository.
+- Measure coverage with `pytest --cov=package_name`.
+
+**Reference:**  
+- [PEP 8 – Style Guide for Python Code](https://peps.python.org/pep-0008/#programming-recommendations)
+- [Testing Guidelines – Pytest Documentation](https://docs.pytest.org/en/stable/goodpractices.html)
+
+**Example CI Integration (GitHub Actions):**
+```yaml
+name: Python CI
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - run: pip install -r requirements.txt
+      - run: pytest --maxfail=1 --disable-warnings -q
+```
+
+---
+
+## 7. Code Style, Linting, and Type Checking
+
+**Maintain a consistent, readable, and typed codebase.**
+
+### Tools
+| Task | Recommended Tool |
+|------|------------------|
+| Code formatting | [Black](https://black.readthedocs.io/en/stable/) |
+| Linting | [Ruff](https://docs.astral.sh/ruff/) or [Flake8](https://flake8.pycqa.org/en/latest/) |
+| Import sorting | [isort](https://pycqa.github.io/isort/) |
+| Type checking | [mypy](https://mypy.readthedocs.io/en/stable/) |
+
+**Reference:**  
+- [PEP 8 – Style Guide for Python Code](https://peps.python.org/pep-0008/)
+- [PEP 484 – Type Hints](https://peps.python.org/pep-0484/)
+
+**Example pre-commit configuration:**
+```yaml
+repos:
+  - repo: https://github.com/psf/black
+    rev: 24.3.0
+    hooks: [{ id: black }]
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.1.0
+    hooks: [{ id: ruff }]
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.10.0
+    hooks: [{ id: mypy }]
+```
+
+---
+
+## 8. Documentation and Docstrings
+
+**Write documentation that grows with your codebase.**
+
+### Recommendations
+- Use descriptive docstrings following [PEP 257](https://peps.python.org/pep-0257/).
+- Use [reStructuredText](https://docutils.sourceforge.io/rst.html) or Markdown for documentation.
+- Consider [Sphinx](https://www.sphinx-doc.org/) or [MkDocs](https://www.mkdocs.org/) for documentation sites.
+- Use type hints for better auto-documentation and IDE support.
+
+**Rationale:**  
+Readable, up-to-date documentation enhances maintainability and team onboarding.
+
+---
+
+## 9. Continuous Integration and Deployment (CI/CD)
+
+**Automate quality checks and deployments.**
+
+### Best Practices
+- Use CI workflows to run tests, linting, and builds automatically.
+- Enforce required checks before merging pull requests.
+- Use environment variables for secrets; avoid storing credentials in code.
+- Optionally integrate publishing with PyPI (`twine upload dist/*`).
+
+**Reference:**  
+- [GitHub Actions Documentation](https://docs.github.com/en/actions)
+- [Python Packaging Authority – Publishing Projects](https://packaging.python.org/en/latest/tutorials/packaging-projects/)
+
+---
+
+## 10. Project Metadata and Packaging
+
+**Provide standardized metadata using `pyproject.toml`.**
+
+Example:
+```toml
+[project]
+name = "example-project"
+version = "0.1.0"
+description = "A well-structured Python project template"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Example Author", email = "author@example.com" }]
+dependencies = ["requests", "pytest"]
+
+[tool.black]
+line-length = 88
+```
+
+**References:**  
+- [PEP 621 – Project Metadata in pyproject.toml](https://peps.python.org/pep-0621/)
+- [PEP 517 – Build System Interface](https://peps.python.org/pep-0517/)
+
+---
+
+## 11. Optional Enhancements
+
+| Enhancement | Purpose | Recommended Tools |
+|--------------|----------|--------------------|
+| Containerization | Reproducible environments | Docker, Podman |
+| Task Automation | Streamline workflows | Makefile, [Taskfile](https://taskfile.dev) |
+| Secrets Management | Secure configuration | `.env`, [python-dotenv](https://pypi.org/project/python-dotenv/) |
+| Static Analysis | Detect potential issues | [Bandit](https://bandit.readthedocs.io/) |
+| Code Metrics | Assess maintainability | [Radon](https://pypi.org/project/radon/) |
+
+---
+
+## 12. Checklist for a High-Quality Python Repository
+
+| Category | Practice | Tools / Standards |
+|-----------|-----------|-------------------|
+| Version Control | Git, semantic versioning | Git, SemVer |
+| Environment Isolation | Virtual environments | venv, Poetry |
+| Dependencies | Explicit, reproducible | pyproject.toml |
+| Structure | Clear, modular | src layout |
+| Testing | Automated | pytest, coverage |
+| Style | Consistent, typed | Black, Ruff, mypy |
+| Documentation | Comprehensive | Sphinx, Markdown |
+| CI/CD | Automated validation | GitHub Actions |
+| Metadata | Standardized | PEP 621 |
+| Licensing | Defined rights | OSI-approved licenses |
+
+---
+
+**References (Summary):**
+- [PEP 8 – Style Guide for Python Code](https://peps.python.org/pep-0008/)
+- [PEP 257 – Docstring Conventions](https://peps.python.org/pep-0257/)
+- [PEP 484 – Type Hints](https://peps.python.org/pep-0484/)
+- [PEP 517 & 518 – Build System Interface](https://peps.python.org/pep-0517/)
+- [PEP 621 – Project Metadata in pyproject.toml](https://peps.python.org/pep-0621/)
+- [Python Packaging User Guide](https://packaging.python.org/)
+- [Pytest Good Practices](https://docs.pytest.org/en/stable/goodpractices.html)
+
+---
+
+> **Summary:**  
+> A Python project repository should be *structured, reproducible, testable, documented, and automated*.  
+> Following these conventions ensures maintainability, scalability, and professional collaboration across teams and time.
+
+xxx