# Contributing to portfolio-optimiser

Thank you for your interest in contributing! This document provides guidelines and instructions
for contributing.

## Code of Conduct

Please read and follow our [Code of Conduct](CODE_OF_CONDUCT.md).

## How to Contribute

### Reporting Issues

- Check existing issues before creating a new one
- Provide clear reproduction steps
- Include relevant environment details (OS, Python version, backend profile)

### Submitting Changes

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes following the conventions below
4. Run the test, lint, and type checks (see Development Setup) and ensure they pass
5. Commit your changes using [Conventional Commits](https://www.conventionalcommits.org/)
   (`type(scope): description`)
6. Push to your branch and open a Pull Request

### Pull Request Guidelines

- Follow the existing code style (`ruff` enforced)
- Type hints everywhere; `mypy`-clean where possible
- Include tests for new functionality — this project uses **load-bearing tests**: a test that
  covers a seam must fail when that seam is detached, not merely pass while wired
- The **deterministic validator is mandatory and blocking** — never make it an optional plugin
- Keep PRs focused on a single change
- Update documentation as needed

## Development Setup

Requires Python ≥ 3.10 and [`uv`](https://docs.astral.sh/uv/).

```bash
# Clone your fork
git clone https://git.fromaitochitta.com/open/portfolio-optimiser.git
cd portfolio-optimiser

# Install dependencies
uv sync

# Run tests
uv run pytest

# Lint and format
uv run ruff check .
uv run ruff format .

# Type-check
uv run mypy src
```

Develop primarily on the **local backend profile** (free); reserve the Azure/Foundry profile for
targeted, minimal verification.

## Questions?

Feel free to open an issue for any questions about contributing.