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
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.

Development Setup

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

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 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:

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.

{
  "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.