Skip to content

Latest commit

 

History

History
executable file
·
134 lines (91 loc) · 5.25 KB

CONTRIBUTING.md

File metadata and controls

executable file
·
134 lines (91 loc) · 5.25 KB
Raw

Contributing to SLIX (Scattered Light Imaging ToolboX)

We would love your input to this repository! We want to make contributing to this project as easy and transparent as possible, whether it is:

  • Reporting a bug
  • Discussing the current state of the code
  • Submitting a fix
  • Proposing new features

The development of SLIX is done through GitHub. A copy of the repository is also hosted on the Forschungszentrum Jülich GitLab. All images shown in the README.md are hosted there.

Pull requests, issues, and feature requests are accepted via GitHub. If you plan to contribute to SLIX, please follow the guidelines below.

Seek support

The Scattered Light Imaging ToolboX is maintained by Jan André Reuter and Miriam Menzel. For bug reports, feature requests, and pull requests, please read the instructions below. For further support, you can contact both per e-mail.

Person E-mail address
Jan André Reuter [email protected]
Miriam Menzel [email protected]

Bug reports

We use GitHub issues to track public bugs. Report a bug by opening a new issue here. Write bug reports with detail, background, and add sample code if possible.

A good bug report should contain:

  • A quick summary and/or background
  • Steps to reproduce
    • Be specific!
    • Give sample code if you can
  • What you expected would happen
  • What actually happens
  • Notes (possibly including why you think this might be happening, or stuff you tried that did not work)

Feature additions

SLIX is a project to support users in the evaluation of Scattered Light Imaging (SLI) measurements of brain slices. For this purpose, several parameter maps are generated with the toolbox. For further analysis, the parameter maps can be visualized using an additional visualization toolbox.

While these features are sufficient for the current framework of the project, other users might have additional requirements for the software. Therefore, pull-requests including additional features and the reporting of errors in the program are welcome.

Currently, SLIX consists of two main files that contain most of the source code: toolbox.py and visualization.py. The first file does most of the work containing methods for preparing the measurement data (extracting relevant information from the SLI profiles), generating the parameter arrays, and reshaping them to an image. The second file contains all methods to visualize the generated parameter maps or even convert the direction maps to unit vectors and display them as colored lines. If any new features shall be added, consider if a new file is more suitable than implementing the new functions into an already existing file.

Pull requests

Pull requests are the best way to propose changes to the codebase. When proposing a pull request, please follow these guidelines:

  • Fork the repo and create your branch from master.
  • If you've added code that should be tested, add tests.
  • Ensure the test suite passes.
  • Make sure your code lints.
  • Issue that pull request!

Testing

SLIX uses pytest to test the code for errors. In addition, flake8 and pylint are used for linting.

Pull requests and commits to the master branch should be automatically tested using GitHub actions with a simple workflow. If you want to test your code locally, follow the next steps:

  1. Change your directory to the root of SLIX
  2. If not done yet, install pytest, flake8 and via pip (or conda in an Anaconda environment)
pip install flake8 pytest

or

conda install flake8 pytest
  1. First, run pylint and flake8 for linting. If there are some issues, fix them before testing your code.
  2. Run pytest and check if there are any errors.

Merging Pull Requests

This section describes how to cleanly merge your pull requests.

1. Rebase

From your project repository, merge from master and rebase your commits (replace pull-request-branch-name as appropriate):

git fetch origin
git checkout -b pull-request-branch-name origin/pull-request-branch-name
git rebase master

2. Push

Update branch with the rebased history:

git push origin pull-request-branch-name --force

The following steps are intended for the maintainers:

3. Merge

git checkout master
git merge --no-ff pull-request-branch-name

4. Test

flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
pytest

5. Version

Modify version in setup.py:

git add setup.py
git commit

6. Push to master

git push origin master

License

By contributing, you agree that your contributions will be licensed under its MIT License.

References

This document was adapted from the open-source contribution guidelines for Facebook's Draft and tqdm