Development Guide

All contributions to coxeter are welcome! Developers are invited to contribute to the framework by pull request to the package repository on GitHub, and all users are welcome to provide contributions in the form of user feedback and bug reports. We recommend discussing new features in form of a proposal on the issue tracker for the appropriate project prior to development.

General Guidelines

All code contributed to coxeter must adhere to the following guidelines:

  • Use the OneFlow model of development: - Both new features and bug fixes should be developed in branches based on main. - Hotfixes (critical bugs that need to be released fast) should be developed in a branch based on the latest tagged release.

  • Avoid external dependencies wherever possible, and avoid introducing any hard dependencies outside the standard Python scientific stack (NumPy, SciPy, etc). Soft dependencies are allowed for specific functionality, but such dependencies cannot impede the installation of coxeter or the use of any other features.

  • All code should adhere to the source code conventions and satisfy the documentation and testing requirements discussed below.

  • Preserve backwards-compatibility whenever possible. Make clear if something must change, and notify package maintainers that merging such changes will require a major release.

To provide a reasonable balance between a high level of backwards compatibility and a reasonable maintenance burden, coxeter has adopted NEP 29 to limit the Python and NumPy versions that will be supported.

Tip

During continuous integration, the code is checked automatically with prek.

Style Guidelines

The coxeter package adheres to a relatively strict set of style guidelines. All code in coxeter should be formatted using ruff. Imports should be formatted using ruff. For guidance on the style, see PEP 8 and the Google Python Style Guide, but any ambiguities should be resolved automatically by running black. All code should of course also follow the principles in PEP 20.

Documentation

API documentation should be written as part of the docstrings of the package in the Google style. There is one notable exception to the guide: class properties should be documented in the getters functions, not as class attributes, to allow for more useful help messages and inheritance of docstrings. Docstrings may be validated using pydocstyle (or using the flake8-docstrings plugin as documented above). The official documentation is generated from the docstrings using Sphinx.

In addition to API documentation, inline comments are highly encouraged. Code should be written as transparently as possible, so the primary goal of documentation should be explaining the algorithms or mathematical concepts underlying the code. Avoid comments that simply restate the nature of lines of code. For example, the comment “solve the system of equations” is uninformative, since the code itself should make this obvious, e.g, np.linalg.solve. On the other hand, the comment “the solution to this system of equations is the intersection of truncation planes” is instructive.

Unit Tests

All code should include a set of tests which test for correct behavior. All tests should be placed in the tests folder at the root of the project. In general, most parts of coxeter primarily require unit tests, but where appropriate integration tests are also welcome. Tests in coxter use the pytest testing framework. To run the tests, simply execute pytest at the root of the repository.

Release Guide

To make a new release of coxeter, see the release guide https://github.com/glotzerlab/coxeter/wiki/Creating-a-release in the coxeter wiki.