Contributing to echopype

We welcome your contributions, large or small!

Contributing on GitHub

For echopype development we use the git forking workflow (also known as fork & pull request workflow), where you first create your own fork of the source GitHub repository https://github.com/OSOceanAcoustics/echopype/ (upstream). Excellent tutorials for this workflow can be found here and here, including guidance on opening pull requests.

Please submit questions or report problems via GitHub issues. If you’re new to GitHub, see these tips for submitting issues: “Creating issues on GitHub”.

Installation for echopype development

To access and test the latest, unreleased development version of echopype, clone the master branch from the source repository:

git clone https://github.com/OSOceanAcoustics/echopype.git

To set up your local environment to contribute to echopype, please follow the git forking workflow as described above. After forking the source repository, clone your fork, then set the source repository as the upstream git remote:

git clone https://github.com/myusername/echopype.git
cd echopype
git remote add upstream https://github.com/OSOceanAcoustics/echopype.git

Create a conda environment for echopype development (replace the Python version with your preferred version):

conda install -c conda-forge -n echopype --yes python=3.8 --file requirements.txt --file requirements-dev.txt
conda activate echopype
# ipykernel is recommended, in order to use with JupyterLab and IPython
# to aid with development. We recommend you install JupyterLab separately
conda install -c conda-forge ipykernel
pip install -e .

See the Installation page to simply install the latest echopype release from conda or PyPI.

Documentation development

Echopype documentation (https://echopype.readthedocs.io) is based on Sphinx and is hosted at Read the Docs. The sphinx files are found in the docs directory, and the source documentation files, written in reStructuredText (.rst) format, are in the docs/source directory. The echopype development conda environment created above will install all required sphinx dependencies. To run sphinx locally:

cd docs
sphinx-build -b html -d _build/doctrees source _build/html

To view the generated HTML files generated by Sphinx, open the docs/_build/html/index.html in your browser.

We also maintain a test version of the documentation at https://doc-test-echopype.readthedocs.io/ for viewing and debugging larger changes.

Test data files

Attention

Echopype previously used Git LFS for managing and accessing large test data files. We have deprecated its use starting with echopype version 0.5.0. The files in https://github.com/OSOceanAcoustics/echopype/tree/master/echopype/test_data are also being deprecated.

Test echosounder data files are managed in a private Google Drive folder and made available via the cormorack/http Docker image on Docker hub; the image is rebuilt daily when new test data are added on Google Drive. See the Running the tests section below for details.

Running the tests

To run the echopype unit tests in echopype/tests, docker and docker-compose will need to be installed if not already installed. To run the tests:

# Install and/or deploy the echopype docker containers for testing
python .ci_helpers/docker/setup-services.py --deploy

# Run the tests
python .ci_helpers/run-test.py --local --pytest-args="-vv"

# When done, "tear down" the docker containers
python .ci_helpers/docker/setup-services.py --tear-down

The tests include reading and writing from locally set up (via docker) http and S3 object-storage sources, the latter via minio.

Continuous integration GitHub Actions

echopype makes extensive use of GitHub Actions for continuous integration (CI) of unit tests and other code quality controls. Every pull request triggers the CI. See echopype/.github/workflows.

The CI tests can be a bit slow, taking up to 20-30 minutes. Under special circumstances, when the submitted changes have a very limited scope (such as contributions to the documentation) or you know exactly what you’re doing (you’re a seasoned echopype contributor), the CI can be skipped. This is done by including the string “[skip ci]” in your last commit’s message.