Thank you for your interest in contributing to Raster Loader!
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.
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.
Create a fork
of the Raster Loader repository.
Use git clone
to clone the repo 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).
As an alternative to setting up a virtual environment, you can also set up a development environment using Docker:
- Install Docker and Docker Compose on your system by following the instructions for your operating system from the official Docker website.
- Use
git clone
to clone the Raster Loader repository to your local machine. - Navigate to the root directory of the repository in your terminal.
- Run
make docker-build
command to build the docker image - Run
make docker-start
to start the development environment. Keep this process running. - Begin your development in a new terminal.
- Run
make docker-test
to run the test suite. - Run a targeted test using pytest flags:
make docker-test PYTEST_FLAGS='-s -k array'
- Run
git checkout -b my-new-feature
to start a new feature branch - Consider writing a test in
raster_loader/tests/
to guide your implementation - Drop into
pdb
when a test fails:make docker-test PYTEST_FLAGS='-s --pdb'
- Run
make docker-enter
to open a terminal inside of the docker container - Run
make docker-stop
to stop the development environment - Run
make docker-remove
to remove docker raster_loader Container/Network/Volume from your system
Note: If you want to make changes to library dependencies (i.e. requirements.txt or requirements-dev.txt) while the container is running, you'll need to rebuild the image using the make docker-build command and restart the container."
Before submitting a pull request, you need to make sure your updates pass tests and 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.
Raster Loader uses pytest for testing. You can run the tests with the following command:
make test
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).
You must also copy the /test/.env.sample
to /test/.env
and edit it to set a
test project and dataset in which the used credentials have permissions to create tables.
If you're working on Windows, please set manually the env variables or the .env file in your terminal.
After setting up your credentials and .env, you can enable the integration test with the following command:
pytest --runintegration
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]"
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.
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.
Raster loader uses Semantic Versioning and Conventional Commits. Format your PR and commit messages accordingly.
To update the changelog before a new release, run the following in your terminal:
$ git-changelog --output CHANGELOG.md --in-place --filter-commits "v0.8.2.."