Skip to content

Latest commit

 

History

History
161 lines (111 loc) · 5.87 KB

CONTRIBUTING.md

File metadata and controls

161 lines (111 loc) · 5.87 KB

Contributor guide

Thank you for your interest in contributing to Raster Loader!

Feature requests and bug reports

Reporting bugs and submitting ideas for new features are great ways to help make Raster Loader better!

To report a bug or request a feature, please create a new issue in the GitHub repository. The issue tracker gives you the option to choose between a bug report and a feature request. It also provides templates with more information on how to file your bug report or feature request.

Contributing code and documentation

Prerequisites

You will need to sign a Contributor License Agreement (CLA) before making a submission. Learn more here.

Raster Loader uses GitHub and git for version control. If you are new to git, you can learn more about it here.

Raster Loader uses a Makefile to automate many aspects of the development process. Using the Makefile requires that you have GNU Make installed.

Setting up your environment

Use git clone to clone the Raster Loader repository to your local machine.

Once the repository is cloned, you can use the Makefile to set up your development environment:

make init

This will create a virtual environment in the env directory and install all necessary dependencies, including a development version of Raster Loader and the Raster Loader CLI.

If you don't have make available, you can open the file Makefile and run the commands manually to set up a virtual environment and install the dependencies.

After creating your environment, you can enter the virtual environment with source env/bin/activate on Linux and macOS or env\bin\Activate.ps1 on Windows (PowerShell).

Tests and linting

Before submitting a pull request, you need to make sure your updates pass tests and linting.

Running linting

To run linting, use the following command:

make lint

This runs flake8 and black. You can also run these tools individually using the flake8 or black command.

Running tests

Raster Loader uses pytest for testing. You can run the tests with the following command:

make tests

This runs all tests in the tests directory. You can also run all tests with the pytest command.

The test suite includes optional integration tests that require credentials for a BigQuery account. To run these tests, you need to set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the path of a JSON file containing your BigQuery credentials (see the GCP documentation for more information). After setting up your credentials, you can enable the integration test with the following command:

pytest --runintegration

Updating tests

All new code needs to be covered by tests. The tests for Raster Loader are located in the raster_loader/tests directory. Each Python module in the package should have its own test module in this directory.

The raster_loader/tests directory also contains tests for the CLI. To learn more about writing tests for the CLI, see the Click documentation.

To only run a specific test file, use the following command:

pytest tests/[test_file_name]

To only run a specific test, use the following command:

pytest -k "[test_name]"

Updating documentation

All new features and updates to features need to be documented.

Raster Loader uses Sphinx to generate documentation.

The documentation is located in the docs directory. You can build the documentation with the following command:

make docs

This will generate the documentation in the docs/build directory.

The documentation follows the Google developer documentation style guide.

The documentation also includes a module API reference. This reference is generated automatically from the docstrings in the code. Please use NumPy style for all your docstrings.

Also included in the documentation is a reference of all available CLI commands. This reference is generated automatically from the docstrings in the CLI code. See the documentation for sphinx-click for more information on how to document the CLI.

Making pull requests

All contributions to Raster Loader are made through pull requests to the the Raster Loader repository.

See the GitHub documentation for more information on how to use pull requests.

All pull requests must reference an issue in the Raster Loader repository (a bug report or feature request, for example). If you can't find an issue to reference, make sure to create a new issue before submitting your pull request.

Pull requests to the Raster Loader repository must pass all automated tests and linting before they are considered for merging. You can use the "WIP" label or mark your pull request as a draft to indicate that it is not ready for review.

Before merging a pull request, the Raster Loader maintainers will review your code and might request changes. You can make changes to your pull request by pushing new commits.