Contributing to Valor
We welcome all contributions, bug reports, bug fixes, documentation improvements, enhancements, and ideas aimed at improving Valor. This doc describes the high-level process for how to contribute to this repository. If you have any questions or comments about this process, please feel free to reach out to us on Slack.
On GitHub
We use Git on GitHub to manage this repo, which means you will need to sign up for a free GitHub account to submit issues, ideas, and pull requests. We use Git for version control to allow contributors from all over the world to work together on this project.
If you are new to Git, these official resources can help bring you up to speed:
- GitHub documentation for forking a repo
- GitHub documentation for collaborating with pull requests
- GitHub documentation for working with forks
Contribution Workflow
Generally, the high-level workflow for contributing to this repo includes:
- Submitting an issue or enhancement request using the appropriate template on GitHub Issues.
- Gathering feedback from devs and the broader community in your issue before starting to code.
- Forking the Valor repo, making your proposed changes, and submitting a pull request (PR). When submitting a PR, please be sure to:
- Update the README.md and/or any relevant docstrings with details of your change.
- Add tests where necessary.
- Run
pre-commit install
on your local repo before your last commit to ensure your changes follow our formatting guidelines. - Double-check that your code passes all of the tests that are automated via GitHub Actions.
- Ping us on Slack to ensure timely review.
- Working with repo maintainers to review and improve your PR before it is merged into the official repo.
For questions or comments on this process, please reach out to us at any time on Slack.
Development Tips and Tricks
Deploying the Back End for Development
Docker Compose
The fastest way to test the API and Python client is via Docker Compose. Start by setting the environment variable POSTGRES_PASSWORD
to your liking, and then start Docker and build the container:
Makefile (requires Docker)
Alternatively, you may want to run the API service from a terminal to enable faster debugging. To start the service, you can run:
pip install api # Install the API in your python environment
export POSTGRES_PASSWORD=password
export POSTGRES_HOST=localhost
make start-postgres-docker # Start the custom postgres service in Docker
make run-migrations # Instantiate the table schemas in Postgres
make start-server # Start the API service locally
Setting Up Your Environment
Creating a Valor-specific Python environment at the start of development can help you avoid dependency and versioning issues later on. To start, we'd recommend activating a new Python environment:
# venv
python3 -m venv .env-valor
source .env-valor/bin/activate
# conda
conda create --name valor python=3.11
conda activate valor
Next, install pre-commit to ensure formatting consistency throughout your repo:
Finally, you're ready to install your client and API modules:
# Install the Client module
python -m pip install -e client/.
# Install the API module
python -m pip install -e api/.
Use pgAdmin to Debug PostGIS
You can use the pgAdmin utility to debug your PostGIS tables as you code. Start by installing pgAdmin, and then select Object > Register > Server
to connect to your PostGIS container. The default connection details are listed below for convenience:
- *Host name/address*: 0.0.0.0
- *Port*: 5432
- *Maintenance database*: postgres
- *Username*: postgres
Running Tests
All of our tests are run automatically via GitHub Actions on every push, so it's important to double-check that your code passes all local tests before committing your code. All of the tests below require pytest
:
Running integration tests
Running back end unit tests
Running back end functional tests
Note: Functional tests require a running instance of PostgreSQL, which you can start using
make start-postgres-docker
.