cd-browser/CONTRIBUTING.md

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

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:

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:

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.