Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.
You can contribute in many ways:
Types of Contributions¶
Report bugs at https://github.com/DigitalSlideArchive/HistomicsTK/issues.
If you are reporting a bug, please include:
Your operating system name and version.
Any details about your local setup that might be helpful in troubleshooting.
Detailed steps to reproduce the bug.
Look through the GitHub issues for bugs. Anything tagged with “bug” is open to whoever wants to implement it.
Look through the GitHub issues for features. Anything tagged with “enhancement” is open to whoever wants to implement it.
HistomicsTK could always use more documentation, whether as part of the official HistomicsTK docs, in docstrings, or even on the web in blog posts, articles, and such.
The best way to send feedback is to file an issue at https://github.com/DigitalSlideArchive/HistomicsTK/issues.
If you are proposing a feature:
Explain in detail how it would work.
Keep the scope as narrow as possible, to make it easier to implement.
Remember that this is a volunteer-driven project, and that contributions are welcome :)
Ready to contribute? Here’s how to set up HistomicsTK for local development.
Fork the HistomicsTK repo on GitHub.
Clone your fork locally:
$ git clone email@example.com:your_name_here/HistomicsTK.git
Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:
$ mkvirtualenv HistomicsTK $ cd HistomicsTK/ $ python -m pip install setuptools-scm Cython>=0.25.2 scikit-build>=0.8.1 cmake>=0.6.0 numpy>=1.12.1 $ python setup.py develop
Of course, any type of virtual python environment will do. These instructions are equally applicable inside conda environments.
Create a branch for local development:
$ git checkout -b name-of-your-bugfix-or-feature
Now you can make your changes locally.
Commit your changes and push your branch to GitHub:
$ git add . $ git commit -m "Your detailed description of your changes." $ git push origin name-of-your-bugfix-or-feature
Submit a pull request through the GitHub website.
Pull Request Guidelines¶
Before you submit a pull request, check that it meets these guidelines:
The pull request should include unit tests (see notes below).
If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and make sure your feature is reflected in one of the .rst files under ./docs/. If an existing module exists and your feature is appended to it, then you can ignore this step as Sphinx will render it automatically. Otherwise, create a new .rst file.
(Optional) Create a Jupyter Notebook or a detailed documentation .rst under ./docs/examples/ to explain exactly how the feature should be used.
The pull request should work for Python 2.7, 3.5, 3.6, and 3.7. Check https://travis-ci.org/DigitalSlideArchive/HistomicsTK/pull_requests and make sure that the tests pass for all supported Python versions.
Unit Testing Notes¶
There are two ‘types` of unit tests on HistomicsTK.
Ordinary unit testing:
All unit testing uses the
pytestmodule, and you should avoid using python’s
unittestmodule. Unit testing using dependency libraries such as
pandasis allowed. Use the standard
test_python_file.pynaming convention. It is important that you check the pytest naming convention to make sure your discovered and actually run. Most of the unit tests are going to be stand-alone, and use data files that are small (e.g. csv files) that are contained (or added to) this repository.
You can run your tests using something like:
$ pytest your_python_file_test.py
Server side testing:
Sometimes you need to write unit tests for features that use an authenticated girder client that is connected to a Digital Slide Archive server. For example, you may want to test a feature that fetches regions from a slide on the DSA server and does some analysis with it. In that case, be sure to use the helper methods provided in
./tests/htk_test_utilities.py. The unit tests in
./histomicstk/annotations_and_masks/tests/annotations_to_masks_handler_test.pyprovide an example of how to handle these situations. Note that when access is need to a very large whole-slide image,
GirderClientis used to provide access to the slide and annotations, which are referenced using
.sha512hash that is present in
girderClient, defined in
tests/htk_test_utilities.pyyields an authenticated girder client that points to the server. If a local girder server docker is running, this will connect to it, otherwise, it will spin up a local girder server, load it with some initial data, and connect to it.
The default behavior initializes the docker image once per module and re-uses it for all tests. This means whatever one unit test changes in the DSA database is persistent for the next unit test. So if, for example, you remove one annotation as part of the first unit test, the next unit test will not have access to that annotation. Once all the unit tests are done, the database is torn down.
If, instead, if you would like to run tests repeatedly (i.e. prototyping), or you would like the changes written by tests in one module to be carried over to the next test module, you may prefer to start the server manually. That way you won’t worry about unknown wait time till the local server is fully initialized. To manually start a DSA docker image:
$ cd HistomicsTK/tests/ $ docker-compose up --build
You can run your tests using something like:
$ pytest test_python_file.py
Of course, you need to have docker installed and to either run this as sudo or be added to the docker group by the system admins.
Please contact the owners if you have questions about this or need support on how to host your test data on
data.kitware.comto make this work.
Travis Integration Notes¶
When you submit a pull request to merge your branch with master, it will be automatically submitted to Travis CI for continuous integration. In plain English, your new branch will be tested to make sure it complies with the standardized coding and documentation style of this repo. If you’d like to help the organizers integrate your changes seamlessly, check to see if the travis CI was passed. Otherwise, examine for errors and see if you can get them fixed. Oftentimes, the errors originate from code and docstring formatting and/or integration of jupyter notebooks into the documentaion examples. Here are some pointers to help you handle some of these issues:
flake8package to check if you comply with the formatting standard. HistomicsTK uses PEP8 standard with some options turned off. The
flake8parameters we use can be found in: https://github.com/girder/girder/blob/2.x-maintenance/setup.cfg
$ flake8 your_python_file.py
You can find
If you like using Vim editor, there is a tool to integrate
flake8with Vim for easy correction of errors at: https://github.com/nvie/vim-flake8
If your text editor does not already have this feature, consider using the package
autopep8to comply with PEP8 standard: https://github.com/hhatto/autopep8 . for example:
$ autopep8 --in-place --aggressive your_python_file.py
pydocstyleto check if you comply with the PEP257 standard for docstrings: https://github.com/PyCQA/pydocstyle . For example:
$ pydocstyle your_python_file.py
If your text editor does not already do this, consider using
docformatterto fix docstrings to standard: https://pypi.org/project/docformatter/ . For example:
$ docformatter --in-place --pre-summary-newline --blank your_python_file.py
If you added new functionality, consider adding the documentation under
docin the form of rst files. Also consider creating Jupyter Notebooks to showcase functionality under
doc/examples/. The documentation is automatically generated using
sphinxwhen you push your pull request and it gets submitted for travis integration. If you added documentation, consider checking if
sphinxthrows errors offline. you may install it from: https://www.sphinx-doc.org/en/master/index.html create a folder for the generated documentation to be saved, let’s say
~/HistomicsTK_test_build/. Then you may run something like:
$ cd HistomicsTK $ sphinx-build ./docs/ ~/HistomicsTK_test_build/ 2>&1 | tee out.log
Then you may check the file
out.logfor build errors.