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 master. - 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 pre-commit. To run these checks locally, you can install and run pre-commit like so:

python -m pip install pre-commit
pre-commit run --all-files

To avoid having commits fail in case you forget to run this, you can set up a git pre-commit hook using pre-commit:

pre-commit install

Style Guidelines#

The coxeter package adheres to a relatively strict set of style guidelines. All code in coxeter should be formatted using black. Imports should be formatted using `isort`_. 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.

Tip

Developers should format their code using black and isort locally. Running the pre-commit hooks will take care of this:

pre-commit run

Alternatively, the tools can be run manually using the commands:

# From the root of the repository
ruff check . --fix

black coxeter/ tests/

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, follow the following steps:

  1. Make a new branch off of master based on the expected new version, e.g. release-2.3.1.

  2. Make any final changes as desired on this branch. Push the changes and ensure all tests are passing as expected on the new branch.

  3. Once the branch is completely finalized, run bumpversion with the appropriate type (patch, minor, major) so that the version now matches the version number in the branch name.

  4. Merge the branch back into master, then push master and push tags. The tagged commit will automatically trigger generation of binaries and upload to PyPI and conda-forge.

  5. Delete the release branch both locally and on the remote.