Initial release: cd-browser v0.1.0

CONTRIBUTING.md

@@ -0,0 +1,181 @@
+# 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.