Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
208 lines (155 loc) · 6.3 KB

CONTRIBUTING.md

File metadata and controls

208 lines (155 loc) · 6.3 KB

How to Contribute

These guidelines aim to maintain code quality, clearly communicate the state of the codebase, and standardize the development workflow. Use your best judgment, and feel free to propose changes to the guidelines by submitting a pull request.

Table of Contents

Preparing the environment

Install Docker Engine using the docker official instructions (avoid snap packages) and the docker compose plugin. No other system dependencies are required.

  1. First, clone the repository.
git clone https://github.com/GlobalFishingWatch/python-app-template.git
  1. Make sure you can build the docker image:
make docker-build
  1. In order to be able to connect to BigQuery, authenticate and configure the project:
make docker-gcp

Install UV for faster installs (otherwise modify Makefile to use regular pip):

make uv
  1. Create virtual environment and activate it:
make venv
./.venv/bin/activate
  1. Install all dependencies for development and the python package in editable mode:
make install
  1. (Optional) Install pre-commit hooks:
make hooks

This step is strongly recommended to maintain code quality and prevent technical debt, particularly regarding documentation, PEP8 compliance, spelling, and type-hinting. If this feels too rigid for your current workflow, at a minimum, make regular use of the provided Makefile commands: format, lint, codespell, and typecheck.

PEP8 checks will be enforced in the GitHub CI.

  1. Make sure you can run unit tests:
make test

Note

Alternatively, you can handle all the development inside a docker container without installing dependencies in a virtual environment. Use make docker-shell to enter a docker container.

Updating dependencies

The requirements.txt file contains all transitive dependencies pinned to specific versions. It is automatically generated using pip-tools, based on the dependencies specified in pyproject.toml. This process ensures reproducibility, allowing the application to run consistently across different environments.

Use pyproject.toml to define high-level dependencies with flexible version constraints (e.g., ~=1.2, >=1.0, <2.0, ...).

To re-compile dependencies, just run

make reqs

If you want to upgrade all dependencies to latest compatible versions, just run:

make reqs-upgrade

Important

Do not modify requirements.txt manually.

Note

Remember that if you change the requirements.txt, you need to rebuild the docker image (make docker-build) in order to use it locally.

Git Workflow

There are two main Git workflows commonly used in software development: Git Flow and GitHub Flow. We encourage using GitHub Flow whenever possible, as it is a lightweight workflow that supports rapid iteration, continuous delivery, and simpler branching. It works especially well for teams that deploy frequently and want to keep their main branch always production-ready. However, if your project involves a long release cycle and a long release process, or you need an unstable shared branch like develop for ongoing integration, then Git Flow may be more appropriate. You can read a summary of both workflows in GITHUB-FLOW.md and GIT-FLOW.md.

How to work on a feature branch

To work on a new feature or fix, create a branch from main or develop, depending on the workflow your team follows.

Try to follow these guidelines:

  • Branch names should be descriptive and concise, all lowercase and with words separated by hyphens "-". Optionally, feature branch names can be prefixed with JIRA ticket. For example, you can use something like PIPELINE-2020-name-of-the-branch.

  • Write clear commit messages. See How to Write a Git Commit Message.

  • Maintain a clean commit history in your feature branch. Use interactive rebase (git rebase -i) to squash, reorder, or edit commits.1

  • If you are not using pre-commit hooks, use the provided Makefile commands (format, lint, codespell, typecheck) as much as possible to maintain code quality.

  • Add unit tests for each piece of code:

    • Avoid connecting to external services during unit tests. Use mocks as needed.
    • Ensure unit tests run as fast as possible.

  • When submitting a Pull Request (PR), ensure it meets the following criteria:

    • It targets the correct base branch (depending on the chosen Git Workflow).
    • It is focused and limited in scope to simplify the review process.
    • Its description includes a link to the related JIRA ticket to support integration between the issue and the PR.

How to deploy

A Google Cloud build that publishes a Docker image is triggered in the following cases:

  • When a commit is merged into main or develop.
  • When a new tag is created.

Footnotes

  1. When performing a rebase, it's acceptable to push --force to your own feature branch, but never on shared branches. Protect main and/or develop from force pushes via GitHub settings. ↩