Skip to content

Latest commit

 

History

History
86 lines (68 loc) · 4.24 KB

CONTRIBUTING.md

File metadata and controls

86 lines (68 loc) · 4.24 KB
Raw

Contributing to Qurro's codebase

If you'd like to make changes to Qurro's codebase, then first off -- thanks a ton! This document describes (briefly) how you'd go about doing this.

Note that these are very in-progress instructions. If you have any questions on things that were missed/unclear here, feel free to file an issue in this repository or email the Qurro development team (mfedarko@ucsd.edu).

Setting up a development environment

We'll use a QIIME 2 environment as the basis for creating our "development environment" -- this is convenient because some of Qurro's tests rely on QIIME 2 being installed. (You could also create a development environment that does not use QIIME 2, some of Qurro's tests would not be able to be run in such an environment.)

  1. Fork Qurro.
  2. Clone your fork of Qurro's source code to your computer.
  3. Create a development conda environment for Qurro:
    1. Install the latest version of QIIME 2 natively, as you would normally. You'll need to install a QIIME 2 version of at least 2022.8.
    2. In a terminal, navigate to the folder to which you cloned your fork of Qurro's source code above. Run pip install -e .[dev] inside this folder to install Qurro along with its normal and development Python dependencies.
    3. Install Black: pip install "black >= 22.3.0". We don't include this in the development dependencies for reasons that are explained later in this document.
    4. Install the various Node.js requirements for testing Qurro's JavaScript code. This can be done by running npm install -g mocha-headless-chrome jshint prettier@2.0.5 nyc. Note that this will install these programs globally on your system.
  4. Run the following commands to verify everything was installed correctly:
qiime dev refresh-cache
make test
make stylecheck

If these commands succeed, then you can start making changes to Qurro.

Before submitting a pull request to Qurro

Both of the following criteria should be followed:

  1. All the tests pass (i.e. make test succeeds).
  2. The code is properly formatted (i.e. make stylecheck succeeds).

Assuming all of Qurro's development dependencies are installed, you can run make style to perform auto-formatting. (In rare occasions I've observed black and flake8 disagreeing, in which case you'd need to manually resolve the problem to get make stylecheck to pass. But I don't think this should happen very often or at all by this point -- contact me if you have questions.)

Common problems

I get a FileNotFoundError that says No such file or directory: 'docs/demos/matching_test/main.js

This is due to how Qurro's test suite is set up. The "matching test" output is generated by Qurro's Python tests, and is used to populate some of the JavaScript tests. Long story short, you'll just need to run make test (or just make pytest) before running make jstest.

When running qiime, qiime qurro, etc. from the CLI I get TypeError: __init__() got multiple values for argument 'obj'

This happens due to a Click version being installed that is unsupported by QIIME 2. See this q2cli issue for context. This can come up in development because one of Qurro's development dependencies (used for auto-formatting and format-checking the Python code) is Black, and later versions of Black rely on Click 8 (and versions of QIIME 2 before 2022.8 do not support Click 8).

Pinning to an older version of Black causes another problem, because -- in this case -- the newer version of Click used in QIIME 2 2022.8 environments will break Black (with this error).

So, we get around this issue by removing Black from our development dependencies completely. If you installed a version of QIIME 2 of at least 2022.8, then installing Black (in the directions above) should not cause problems (or at least it should not cause these particular problems).

Acknowledgements

This document was loosely based on Emperor's CONTRIBUTING.md file.