# 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.