Skip to content

Contributing

Thank you for contributing to Myna.

Open a pull request against main with a clear description of your changes. When opening the pull request, complete the repository PR template to include details relevant to your change. All pull requests must pass CI checks and be approved by at least one Myna developer.

Table of Contents

Contributor Workflow

1. Install development dependencies

Formatting and testing tools are included in optional development dependencies:

pip install -e .[dev]

2. Make your desired changes.

3. Run automatic commit checks with pre-commit

Use pre-commit to ensure local changes are ready for review.

  1. Install it locally:
pip install pre-commit
  1. Enable it in this repository:
pre-commit install
  1. Commit normally and allow hooks to run.

To skip hooks for a single commit, use --no-verify. You can also run checks manually using the commands below.

4. Run formatting and linting

Myna uses ruff for formatting and linting. Run these from the repository root:

ruff format
ruff check

pylint also runs in GitHub CI for deeper analysis. Some warnings are allowed, but CI will fail if too many new warnings reduce quality below the configured threshold.

5. Run unit tests

Myna uses pytest. Run all tests from the repository root:

python -m pytest

Commit Message Convention

Use Conventional Commits:

<type>(<optional scope>): <description>

<optional body>

<optional footer>

Allowed Types

  • build: Changes that affect the build system or external dependencies
  • chore: Other changes that don't modify src or test files
  • ci: Changes to CI configuration files and scripts
  • docs: Documentation only changes
  • feat: A new feature
  • fix: A bug fix
  • perf: A code change that improves performance
  • refactor: A code change that neither fixes a bug nor adds a feature
  • revert: Reverts a previous commit
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc.)
  • test: Adding missing tests or correcting existing tests

Scope

Scope is optional, but recommended when it improves clarity.

  • Use lowercase, short, subsystem-focused names.
  • Prefer one scope when possible.
  • Use multiple scopes only for tightly related areas.

Multi-scope format:

<type>(<scope1>, <scope2>): <description>

Suggested scopes:

  • cli
  • workflow
  • metadata
  • components
  • files
  • utils
  • database
  • additivefoam
  • openfoam
  • exaca
  • thesis
  • rve
  • deer
  • bnpy
  • cubit
  • adamantine
  • peregrine
  • tests
  • docs
  • ci

Examples:

  • feat(cli): add dry-run flag to configure command
  • refactor(workflow, metadata): simplify metadata loading in run pipeline

Subject Line

  • Use imperative voice (add, fix, update).
  • Start with a lowercase word.
  • Do not end with punctuation.
  • Keep it concise and specific.

Examples:

  • Valid: fix(metadata): handle missing layer-thickness field
  • Invalid: fix(metadata): Fixed missing layer-thickness field

Breaking Changes

Breaking changes are considered to be anything which breaks a previous user input or user interface. Breaking changes also include substantive change to application behavior due to internal changes (e.g. new default values).

Use either:

  1. ! before the colon:
<type>(<optional scope>)!: <description>
  1. A BREAKING CHANGE: footer:
<type>(<optional scope>): <description>

<optional body>

BREAKING CHANGE: <description of the breaking change>

Pull Request Title Format

PR titles follow the same format and types as commit messages:

<type>(<optional scope>): <description>

Breaking-change PR title:

<type>(<optional scope>)!: <description>

Examples:

  • feat(cli): add support for batch exports
  • fix(database)!: remove deprecated peregrine schema alias

Branch Naming

Branch names follow a similar convention to commit messages:

<type>/<description>

Allowed Types

Branch types are the same as commit types:

  • build: Changes that affect the build system or external dependencies
  • chore: Other changes that don't modify src or test files
  • ci: Changes to CI configuration files and scripts
  • docs: Documentation only changes
  • feat: A new feature
  • fix: A bug fix
  • perf: A code change that improves performance
  • refactor: A code change that neither fixes a bug nor adds a feature
  • revert: Reverts a previous commit
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc.)
  • test: Adding missing tests or correcting existing tests

Description

  • Use lowercase, hyphen-separated words.
  • Keep it concise and specific.
  • Include issue identifiers when useful.

Examples:

  • feat/add-export-support
  • ci/fix-pipeline
  • fix/113-handle-missing-field