Skip to content

Latest commit

 

History

History
120 lines (97 loc) · 4.8 KB

CONTRIBUTING.md

File metadata and controls

120 lines (97 loc) · 4.8 KB
Raw

Contributing Guide

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

Installation

To set up for local development (requires poetry):

$ git clone https://github.com/pyinat/pyinaturalist.git
$ cd pyinaturalist
$ poetry install -v -E docs

Contribution Guidelines

Pull Requests

Here are some general guidelines for submitting a pull request:

  • If the changes are trivial, just submit a PR and briefly explain the changes in the description.
  • Otherwise, please submit an issue describing the proposed change prior to submitting a PR.
  • Make sure the code is tested, documented, and type-annotated (as described in sections below).
  • Submit the PR to be merged into the main branch.

Tests

We use the pytest framework for unit testing. Just run the pytest command to run locally.

Testing supported python versions

For PRs, GitHub Actions will run these tests for each supported python version.

You can use nox to do this locally, if needed:

nox -e test

Or to run tests for a specific python version:

nox -e test-3.10

See nox --list for a ful list of available commands.

Documentation

For PRs, please include docstrings for all functions and classes.

To build the docs locally:

$ nox -e docs

To preview:

# MacOS:
$ open docs/_build/html/index.html
# Linux:
$ xdg-open docs/_build/html/index.html

You can also use sphinx-autobuild to rebuild the docs and live reload in the browser whenever doc contents change:

$ nox -e livedocs

Project documentation is generated using Sphinx, MyST, and several Sphinx extensions and custom templates. See conf.py for more details.

Documentation is automatically built by ReadTheDocs whenever code is merged into main:

For any new or changed behavior, add a brief high-level summary to HISTORY.md. This isn't needed for internal changes (tests, other docs, refactoring, etc.).

Type Annotations

All parameters and return values should have type annotations, which will be checked by mypy and will show up in the documentation.

Linting & Formatting

Code checking and formatting tools used include:

All of these will be run by GitHub Actions on pull requests. You can also run them locally with:

nox -e lint

Pre-Commit Hooks

Optionally, you can use pre-commit to automatically run all of these checks before a commit is made:

pre-commit install

This can save you some time in that it will show you errors immediately rather than waiting for CI jobs to complete, or if you forget to manually run the checks before committing.

You can disable these hooks at any time with:

pre-commit uninstall

Releases

Notes for maintainers on publishing new releases:

Releases are based on git tags. GitHub Actions will build and deploy packages to PyPi on tagged commits on the main branch. Release steps:

  • Update the version in both pyproject.toml and pyinaturalist/__init__.py
  • Update the release notes in HISTORY.md
  • Push a new tag, e.g.: git tag v0.1.0 && git push --tags
  • This will trigger a deployment. Verify that this completes successfully and that the new version can be installed from PyPI with pip install pyinaturalist.
  • Verify that the docs are built and published to Read The Docs.
  • A PR for a new Conda release will be created by a bot on the pyinaturalist-feedstock repo. It may take a couple hours after PyPI deployment for this to happen. Typically this will be auto-merged and built without any manual action required. Just verify that this completes successfully and that the new version can be installed from conda-forge with conda install -c conda-forge pyinaturalist.
    • If new dependencies have been added, then those must also be added to the conda recipe.
  • A Docker build will be triggered for pyinaturalist-notebook. Verify that this successfully gets deployed to Docker Hub.