Contributing#

Thank you for your interest in arim! There are many ways to contribute, including:

  • Reporting issues for bug fixes,

  • Writing documentation,

  • Writing example scripts to help users get up to speed quickly,

  • Writing unit tests to ensure the code works as intended,

  • Adding new features.

Developer installation#

Installation for development requires extra packages for testing, running the code formatting and linting, and building documentation. The recommended instructions are as follows.

First, create a fork of arim under your own Github account.

Install hatch.

Clone your forked arim repository locally.

Create a new virtual environment and install the dependencies. You can do this from any prompt or terminal window

cd <arim-clone-directory>
hatch env create

To activate this virtual environment, use hatch shell. Refer to the hatch documentation for further details.

Make sure you have a working conda or mamba installation. For the remainder of this section, mamba will be used - replace this with conda if this is your preferred package manager.

Clone your forked arim repository locally.

Create a new mamba environment, and install arim.

mamba create -n arim-env
cd <arim-clone-directory>
pip install -e .

This will install the required dependencies, as well as arim in editable mode. Any changes you make to the code base in this folder will therefore be used when running arim.

Code quality guidelines#

Adhering to a common code style helps make the code more readable. As code is written once but read multiple times, it is important that it is written well to save time in the long run. Meaningful and expressive variable and function names, with no or little abbreviation, are essential.

arim code follows the general guidelines defined in Python PEP-8, with the amendments defined in the following sections.

Code formatting and linting#

arim uses the black formatter and the ruff linter. To format and lint from your environment, use

hatch run lint:fmt

To run a check without changing any code, use

hatch run lint:check

The linter configuration is defined in pyproject.toml.

Docstrings#

Docstrings for functions, classes and modules follow numpy’s docstring format

Documentation#

arim’s documentation is powered by Sphinx, with the most recent version deployed using Github Pages.

The documentation is generated from two sources:

  1. The files found in docs/source, formatted as ReStructuredText, and

  2. The docstrings in the codebase, compiled via autosummary.

If including academic references, please use the author-date style from the Chicago Manual of Style, e.g.

  • Holmes, Caroline, Bruce W. Drinkwater, and Paul D. Wilcox. 2005. ‘Post-Processing of the Full Matrix of Ultrasonic Transmit–receive Array Data for Non-Destructive Evaluation’. NDT & E International 38 (8): 701–11. doi:10.1016/j.ndteint.2005.04.002.

Building the documentation#

arim uses Github Actions to automatically build the documentation when new pushes are made, or when a new pull request is accepted. Before this happens, please test that it works by building a version locally:

cd <arim-clone-directory>/docs
hatch shell default
make html

cd <arim-clone-directory>/docs
mamba activate arim-env
make html

The output will be found in docs/build/html.

Version control#

A commit should contain one functional change. In other words, it should not contain multiple unrelated features. It is also important to use informative commit messages.

It is best practice to only push to branch master versions of arim which successfully pass all tests. When developing new features, please create a new branch first to develop the feature locally. Add tests, docstrings, examples, and if necessary update the user guides in the documentation. Finally, only when all tests are passing, should you finally create a pull request to master. (See this article for more details).

Testing#

Unit tests ensure that a given function returns the intended results at the time of commit, as well as much later down the line (i.e. it is non-regressive). arim uses pytest to do unit testing. Tests are defined in the tests directory. Please consider adding new tests!

To run the tests, use

hatch run test

mamba activate arim-env
pytest

All tests must pass before a pull request will be accepted into the master branch.

Pull requests#

You can propose changes to arim using pull requests. By submitting a pull request, you accept that the proposed changes are licensed under the MIT license. The proposed changes must also comply with arim’s code quality guidelines.

Releases#

Releases should be made when new features are added. To create a release, 1. Ensure all unit tests pass. 2. Change arim’s version number in src/arim/__init__.py, following the PEP 440 convention. Commit with an instructive description. 3. Assign a tag to the release commit. For example, if the version number is 1.1, the tag name should be “v1.1”. 4. Build the documentation, and save the HTML files in a zip names “documentation.zip”, outside of the tracked repository. 5. Create a wheel package

hatch build

6. Create a new release on Github. Select the newly created tag, and describe the changes in this version. Attach both the wheel (.whl) file and documentation.zip.