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¶
The PyCalphad test suite is one of the most valuable cumulative contributions of the library that ensures quality and continuous improvement.
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.
Tests are for verifying correctness. Prefer testing with real databases.
Most tests should be small, fast, and test only one thing so if/when the test fails, it is obvious where the problem lies.
Tests for
Model(and subclass) implementations should prefer to usepycalphad.tests.test_energy.check_outputorpycalphad.tests.test_energy.check_energyrather than usingWorkspace(orequilibrium) as that also exercises the minimizer.Tests that exercise the minimizer (synonym: solver) should be marked
@pytest.mark.solver
PyCalphad provides custom pytest fixtures
pycalphad.tests.fixtures.select_databaseandpycalphad.tests.fixtures.load_databasefor loading databases frompycalphad.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.