Skip to content

Latest commit

 

History

History
124 lines (78 loc) · 5.06 KB

CONTRIBUTING.md

File metadata and controls

124 lines (78 loc) · 5.06 KB

Contributing to arim

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

  • reporting issues to fix bugs,
  • writing documentation,
  • writing example scripts to help users to get started quickly,
  • writing unit tests to ensure the code works as intended,
  • adding new features.

Developer installation

A developer installation requires extra packages for testing, running the code formatter and linter, and building the documentation.

The recommended instructions are as follows.

Install hatch.

Clone arim repository locally.

Create a new virtual environment and install the dependencies:

cd arim
hatch env create

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

Code quality guidelines

Adhering to a common code style helps making the code more readable.

Code is written only once, but read multiple times, so writing readable code is essential to save time in the long run. Meaningful variable and function names, with no or little abbreviation, are in particular 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 black code formatter and ruff linter.

Format and lint:

hatch run lint:fmt

To only check, without changing the code, use hatch run lint:check.

The linter configuration is defined in pyproject.toml.

Docstring

Docstrings of functions, classes and modules use numpy's docstring format.

Documentation

arim's documentation is powered by Sphinx.

The documentation is generated from two sources:

  1. the .rst files in docs/source, formatted in ReStructuredText,
  2. the docstrings in arim's Python code, via autosummary

For academic references, please use the author-date style from the Chicago Manual of Style, for example:

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

  1. Delete the cache of autosummary by deleting the directory docs/source/_autosummary
  2. In the directory docs, type in a terminal:
hatch shell default
make html

The output is in docs/source/html.

Version control discipline

A commit must contain one functional change. In other words a commit must not contain changes in several unrelated features. Always use informative commit messages.

Please push in branch master only versions of arim which successfully pass all tests. When developing new complex features, please a create a new branch first, develop the feature, add tests, and finally create a pull request. to master when it is ready (feature branch workflow).

Pull request

You can propose changes to arim using pull requests (Github's guide for pull requests). By submitting a pull request, you accept that the proposed changes are licensed under the MIT license. The proposed changes must comply with arim's code convention, as per previous section.

Testing

Unit tests ensure that a given function returns intended results at the time of commit and later on (non-regression). Unit testing in arim is powered by pytest. The tests are defined in directory tests. Consider adding new tests!

To run the unit tests, use the following command:

hatch run test

All tests must pass.

Releasing

To create a release:

  1. Ensure all unit tests pass (see 'Testing' section)
  2. Change arim's version number arim/__init__.py, following PEP 440 convention, then commit with an instructive description such as "Release version 1.0"
  3. Assign a tag to the release commit. The tag name should be "v1.0" if the version number is 0.1.
  4. Build the documentation, save the HTML files in a zip file named "documentation.zip"
  5. Create a wheel package with
hatch build

The result is a .whl file in the directory dist, for example arim-0.8-py3-none-any.whl.

  1. Create a release on Github. Select the newly created tag. Describe the changes of this new version. Attach the documentation.zip file and the wheel (.whl) file to it.