Contributing to PyCalphad

This is a guide for best practices on making contributions to PyCalphad. See Onboarding as a Developer for instructions on setting up your development environment.

Tests

Test Coverage

The PyCalphad test suite is one of the most valuable cumulative contributions of the library that ensures quality and continuous improvement.

  1. PyCalphad tests aim for high code coverage. Ideally every PR has a net improvement on test coverage without trivially exercising code paths to improve coverage metrics.

  2. Tests are for verifying correctness. Prefer testing with real databases.

  3. Most tests should be small, fast, and test only one thing so if/when the test fails, it is obvious where the problem lies.

    1. Tests for Model (and subclass) implementations should prefer to use pycalphad.tests.test_energy.check_output or pycalphad.tests.test_energy.check_energy rather than using Workspace (or equilibrium) as that also exercises the minimizer.

    2. Tests that exercise the minimizer (synonym: solver) should be marked @pytest.mark.solver

  4. PyCalphad provides custom pytest fixtures pycalphad.tests.fixtures.select_database and pycalphad.tests.fixtures.load_database for loading databases from pycalphad.tests.databases. Prefer not to add new databases to the test suite if a feature or bug can be exercised with a database already present in the test suite.

Contribution Workflow

All changes are made through GitHub pull requests and are reviewed by a maintainer before merging. Before submitting a pull request, please open an issue or comment on an existing relevant one to discuss the changes you plan to make. A little alignment upfront prevents significant re-work later.

AI Policy

Contributors may use any tools they would like to craft contributions, but there must be a human-in-the-loop.

The PyCalphad project values human contributors more than their contributions. Maintainers/Reviewers expect to engage with humans, not with AI. We encourage new contributors to _not_ use AI as they learn the project.

Human contributors, are responsible for:

  • authoring issue and pull request descriptions

  • understanding every change

  • reviewing and testing the changes, and

  • ensuring the changes are correct (to the best of their ability)

Please read Numba’s AI Tool Use Policy, which informed our policy, for additional details and rationale.