182 lines
4.0 KiB
Markdown
182 lines
4.0 KiB
Markdown
# Contributing
|
|
|
|
Thank you for your interest in contributing to this project.
|
|
|
|
This repository is intended to be a clean, reusable, and professional Python project template. Contributions should preserve that goal.
|
|
|
|
## General Principles
|
|
|
|
- Keep the template generic and adaptable.
|
|
- Prefer clarity over cleverness.
|
|
- Avoid unnecessary complexity.
|
|
- Follow the existing project structure and conventions.
|
|
- Write all code, comments, docstrings, and documentation in English.
|
|
|
|
## Development Setup
|
|
|
|
It is recommended to use the provided Makefile.
|
|
|
|
### First-time setup
|
|
|
|
```bash
|
|
make dev
|
|
# Contributing
|
|
|
|
Thank you for your interest in contributing to this project.
|
|
|
|
This repository is intended to be a **clean, reusable, and professional Python project template**.
|
|
All contributions should aim to **improve the template without making it specific to a single project**.
|
|
|
|
The goal is to keep this repository:
|
|
|
|
- simple
|
|
- professional
|
|
- maintainable
|
|
- widely reusable
|
|
|
|
---
|
|
|
|
# General Principles
|
|
|
|
When contributing, please follow these principles:
|
|
|
|
- Keep the template **generic and adaptable**.
|
|
- Prefer **clarity over cleverness**.
|
|
- Avoid unnecessary complexity.
|
|
- Follow the existing **project structure and conventions**.
|
|
- Keep the repository **easy to understand for new developers**.
|
|
- Write all **code, comments, docstrings, and documentation in English**.
|
|
|
|
This repository should remain a **solid starting point for many different types of Python projects**.
|
|
|
|
---
|
|
|
|
# Development Setup
|
|
|
|
It is recommended to use the provided **Makefile** to set up the development environment.
|
|
|
|
## First-time setup
|
|
|
|
```bash
|
|
make dev
|
|
```
|
|
|
|
This command will:
|
|
|
|
- create the `.venv` virtual environment
|
|
- install project dependencies
|
|
- install development tools
|
|
- configure `pre-commit` hooks
|
|
|
|
---
|
|
|
|
# Development Workflow
|
|
|
|
Typical workflow when working on the project:
|
|
|
|
```bash
|
|
make fix
|
|
make quality
|
|
make run
|
|
```
|
|
|
|
Command summary:
|
|
|
|
| Command | Description |
|
|
|-------|-------------|
|
|
| `make dev` | bootstrap development environment |
|
|
| `make install` | reinstall dependencies |
|
|
| `make fix` | auto-format and fix code issues |
|
|
| `make quality` | run formatting, linting, type checks, and tests |
|
|
| `make ci` | simulate CI validation |
|
|
| `make doctor` | show environment and tool versions |
|
|
| `make run` | run the application |
|
|
|
|
---
|
|
|
|
# Code Standards
|
|
|
|
All contributions should follow these standards:
|
|
|
|
- Python **3.11+**
|
|
- Use **type hints** where appropriate
|
|
- Write **clean and modular code**
|
|
- Prefer **readable code over clever shortcuts**
|
|
- Avoid dead code
|
|
- Use **consistent docstrings** for public APIs
|
|
|
|
Tools used in this project:
|
|
|
|
- **black** → formatting
|
|
- **ruff** → linting
|
|
- **mypy** → static typing
|
|
- **pytest** → testing
|
|
|
|
---
|
|
|
|
# Quality Checks
|
|
|
|
Before submitting changes, run:
|
|
|
|
```bash
|
|
make fix
|
|
make quality
|
|
pre-commit run --all-files
|
|
```
|
|
|
|
All checks should pass before committing.
|
|
|
|
---
|
|
|
|
# Documentation
|
|
|
|
If you modify project structure, development workflow, or setup instructions, please update the relevant documentation:
|
|
|
|
- `README.md`
|
|
- `CHANGELOG.md`
|
|
- `instructions-agent.md`
|
|
|
|
Clear documentation is as important as clean code.
|
|
|
|
---
|
|
|
|
# Commit Messages
|
|
|
|
Use clear and concise commit messages.
|
|
|
|
Examples:
|
|
|
|
```
|
|
Add make doctor command
|
|
Improve README template usage instructions
|
|
Add environment configuration example
|
|
Fix formatting issues
|
|
```
|
|
|
|
Good commit messages make the project history easier to understand.
|
|
|
|
---
|
|
|
|
# Scope of Contributions
|
|
|
|
Good contributions include:
|
|
|
|
- improving the project structure
|
|
- improving development workflow
|
|
- improving documentation
|
|
- improving tooling and automation
|
|
- fixing template inconsistencies
|
|
- simplifying developer experience
|
|
|
|
Please avoid turning this repository into a **project-specific application**.
|
|
|
|
This repository should remain a **general-purpose Python template**.
|
|
|
|
---
|
|
|
|
# Acknowledgements
|
|
|
|
This template was created by **Saky**, drawing on many years of professional software engineering experience and with the assistance of modern AI development tools.
|
|
|
|
Contributions that improve the template while preserving its simplicity are always welcome.
|