Contributing

This page is intended for project developers. It describes the development workflow.

Requirements

To develop the present project you would need:

An Unix-like environment.
uv project manager.
git version control system.
A CDSE account.

Contribution Workflow

Clone

git clone git@github.com:CoLAB-ATLANTIC/s3lst-ds.git
cd s3lst-ds

Branch

Create a feature branch for your changes from main:
```
git switch main
git pull
git switch -c FEATURE/MY_CHANGE
```
where FEATURE/MY_CHANGE is the name of the branch.

Tip

Examples of development names

feature/add-download-endpoint
fix/rasterio-import-error
docs/update-contributing
refactor/download-service
perf/parallel-downloads
test/add-download-tests

Install dependencies

Create projects's python environment with all dependency groups including the optional ones in accordance with pyproject.toml:
```
uv sync --all-groups --all-extras
```
Install the backend SNAP Java package (if not already installed) and subsequently configure it using uv:
```
uv run s3lst-ds-install-snap
```
Install all git hooks in accordance with .pre-commit-config.yaml:
```
uv run pre-commit install
```
Safely set your CDSE credentials as environment variables of the system:
```
uv run s3lst-ds-set-cdse
```

Note

CDSE credentials

CDSE credentials are required to download Sentinel-3 data. Script s3lst-ds-set-cdse will prompt the user to provide their CDSE mail and password. The script will subsequently write them to file ~/.config/cdse_credentials.sh with user-only read and write permissions and source it in ~/.bashrc file. You may check the created credentials file using the command:

nano ~/.config/cdse_credentials.sh

Note that if you would like to remove the credentials from the file at a later time, you may run:

uv run s3lst-ds-unset-cdse

Make changes to the Python source code

Make your changes in the code by following the coding style guide of Python Enhancement Proposal 8 (PEP 8).

Make changes to the documentattion source code

Render HTML in a local development server from the source documenting code at the /docs folder and auto-reload for changes in it:
```
uv run mkdocs serve
```

Commit and push changes

Commit your changes and push them to the remote repo:
```
git add -A
git commit -m "MESSAGE"
git push -u origin FEATURE/MY_CHANGE
```
where MESSAGE is the commit message to set.

Note

Automatic executions on commit

As defined in .pre-commit-config.yaml, pre-commit package is in this project used to run several git hooks on commit:

Project syncing (using uv sync).
uv.lock file update (using uv lock).
Code lint check (using ruff check).
Code formatting (using ruff format).

If any of these fails, the commit operation is aborted. Note that project syncing is also automatically performed after checkouts, merging, amending and rebasing.

Automatic executions after a push

As defined in the GitHub workflow file ci.yml, several are executed by GitHub after a push:

Code lint check (using ruff check).
Code format check (using ruff format --check).

Note that regardless of any of these failing, the push proceeds.

Open pull request

In GitHub open a pull request using main branch as base and the development branch as compare one, so that other developers and maintainers may review the changes, comment on and approve them and also request corrections.

Note

Automatic executions on the creation of a pull request

As defined in the GitHub workflow file ci.yml, the push-specific jobs are also run on the creation of a pull request.