Contributing

almirah was initially developed to handle and maintain neuroimaging datasets. But we believe this can be useful for other datasets too!

We happily accept contributions for all things related to dataset management.

If you wish to add a new feature or fix a bug:

  1. Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug.

  2. Fork the repository on Github to start making your changes.

  3. Write a test which shows that the bug was fixed or that the feature works as expected.

  4. Format your changes with black.

  5. Update documentation if required.

  6. Add a changelog entry if required.

  7. Send a pull request and bug us till it gets merged and published.

Setting up your development environment

In order to setup the development environment all you need is poetry installed in your machine.

$ git clone git@github.com:bhallalab/almriah.git
$ cd almirah
$ poetry install

Note

File format conversion functionality depends on external non-python dependencies such as dcm2niix and edf2asc. The installation of these is left as an exercise to the user. Just kidding, these will be added in later.

Running tests

We use pytest for running the test suite.

$ pytest

Contributing to documentation

You can build the docs locally using sphinx.

$ sphinx-build -b html docs/source docs/build/html

However, if you have run sphinx-quickstart, it creates a Makefile and make.bat which make it easier.

$ make html

The documentation is built continuously on GitHub Actions with every push request. Hence, it is not necessary to push documentation builds to the repository.

If you are planning a release and want to update the changelog in docs, run towncrier build --version X.Y.Z before building check the final look.

Releases

A release candidate can be created by any contributor.

  • Announce intent to release by communicating to all contributors.

  • Run towncrier build --version X.Y.Z to update CHANGES.rst with the release notes. Adjust as necessary.

  • Update pyproject.toml and conf.py with the proper version number.

  • Commit the changes to your branch and tag the commit with version number, namely X.Y.Z.

  • Create a pull request!