Contributing to portfolio-optimiser-claude

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.

How to Contribute

Reporting Issues

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

Submitting Changes

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes following the conventions below
Run the test, lint, and type checks (see Development Setup) and ensure they pass
Commit your changes using Conventional Commits (type(scope): description)
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.

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

# Install dependencies
uv sync

# Run tests (offline, no API key required)
uv run pytest

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

# Type-check (strict)
uv run mypy src

Tests run offline without an API key; live runs use the Claude API — keep ANTHROPIC_API_KEY in your environment, never commit it.

Questions?

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

1.9 KiB Raw Permalink Blame History