# Development notes


# How to contribute to Matr1x


## Did you find a bug or have a suggestion for improvement?

If you find a bug:

1.  Check if the issue already exists on [GitHub](https://github.com/andythomas/matr1x/issues)
2.  If not, create an issue using the bug template.
3.  Follow the instructions and hints on the bug template.


## Submitting Pull Requests

1.  Fork the repository.
2.  Create a new branch for your changes.
3.  Make your changes and commit them with clear, descriptive messages.
4.  Format the code with `ruff format` and check it with `ruff check` and `ty check`.
5.  Ensure the new code passes the test suite: `pytest`.
6.  Push to your fork and submit a pull request to the `development` branch using [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).


## Development Setup

We recommend setting up your development environment using a `uv` virtual environment. Make sure your installation has all the required dependencies.

``` bash
uv sync --all-extras --all-groups
```


## Code Style

- Use meaningful variable and function names
- Add docstrings to functions and classes in numpy format
- Keep functions focused and concise
- The exact style guide is enforced by `ruff`.


# Questions?

Please open an issue for questions or discussions about contributing.


# Conventional Commits

Please note that [Commitizen](https://github.com/commitizen-tools/commitizen) can assist with message generation.


# Type Checking

Early bug detection relies on strict type boundaries. To prevent type erosion, two core constraints apply:

- **Within a class:** `Any` and `Unknown` should not cross method signatures.
- **Outside a class:** `Any` and `Unknown` must never cross public class boundaries.


# Pre-commit hooks

For anyone interested to run the pre-commit hooks locally and also using the exact versions fixed by uv.lock you can use:

``` yaml
repos:

- repo: local
  hooks:

  # Run the linter using local ruff
  - id: ruff-check
    name: ruff check
    entry: uv run ruff check --fix
    language: system
    types_or: [python, pyi]
    require_serial: true

  # Run the formatter using local ruff
  - id: ruff-format
    name: ruff format
    entry: uv run ruff format
    language: system
    types_or: [python, pyi]
    require_serial: true

  # Run ty type checker using local ty
  - id: ty
    name: ty type checker
    entry: uv run ty check
    language: system
    types_or: [python, pyi]

  # Run complexipy using local complexipy
  - id: complexipy
    name: complexipy
    entry: uv run complexipy .
    language: system
    types_or: [python, pyi]
    pass_filenames: false
```

add the `pre-commit-config.yaml` to `.git/info/exclude`.


# Specific editor settings


## Zed editor settings

In case you use the Zed editor you may benefit from including these settings for this project and install the `toml`, `ruff` and `ty` extensions. Note that you have to replace `<project-root>` with the directory on your system.

``` json
{
  "languages": {
    "Python": {
      "language_servers": ["ruff", "ty"]
    }
  },
  "lsp": {
    "ty": {
      "binary": {
        "path": "<project-root>/.venv/bin/ty",
        "arguments": ["server"]
      }
    },
    "ruff": {
      "binary": {
        "path": "<project-root>/.venv/bin/ruff",
        "arguments": ["server"]
      }
    }
  },
  "terminal": {
    "detect_venv": {
      "on": {
        "directories": [".venv"],
        "activate_script": "default"
      }
    }
  }
}
```


## Visual Studio Code settings

If you use Visual Studio Code, you can install the `Python`, `ruff` and `ty` extensions.