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

### Pull requests are not accepted

The pull-request tab is **switched off** on this forge, across every repository in the
organisation. That is a published position, not an oversight: this project is solo-maintained,
and an enabled-but-permanently-empty PR queue would promise a review capacity that does not
exist.

Two routes are open instead:

- **Issues** — welcome, and read as signals. A well-argued issue carries the same information
  as a patch and costs you less to write.
- **Fork-and-own** — the recommended adoption model. The licence is MIT: fork it, take it in
  your own direction, and you owe nothing back.

## Standards this project holds itself to

These are the conventions the code is written against. They are worth knowing if you fork, and
they are what an issue about the code will be weighed against:

- Follow the existing code style (`ruff` enforced)
- Type hints everywhere; `mypy`-clean where possible
- Commit with [Conventional Commits](https://www.conventionalcommits.org/)
  (`type(scope): description`)
- New functionality comes with tests — 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
- Documentation is updated in the same change

## Development Setup

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

```bash
# Clone (upstream, or your own 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.