# Contributor Guide

Thank you for your interest in improving this project. This project is public domain under the [CC0 1.0 Universal license](https://creativecommons.org/publicdomain/zero/1.0/legalcode)
and welcomes contributions in the form of bug reports, feature requests, and pull requests.

Here is a list of important resources for contributors:

- [Source Code](https://code.usgs.gov/wma/nhgf/toolsteam/gdptools)
- [Documentation](https://gdptools.readthedocs.io/)
- [Issue Tracker](https://code.usgs.gov/wma/nhgf/toolsteam/gdptools/issues)
- [Code of Conduct](https://gdptools.readthedocs.io/en/latest/codeofconduct.html)

## How to report a bug

Report bugs on the [Issue Tracker](https://code.usgs.gov/wma/nhgf/toolsteam/gdptools/issues).

When filing an issue, make sure to answer these questions:

- Which operating system and Python version are you using?
- Which version of this project are you using?
- What did you do?
- What did you expect to see?
- What did you see instead?

The best way to get your bug fixed is to provide a test case, and/or
steps to reproduce the issue.

## How to request a feature

Request features on the [Issue
Tracker](https://code.usgs.gov/wma/nhgf/toolsteam/gdptools/issues).

## How to set up your development environment

You need Python 3.10+ and [uv](https://docs.astral.sh/uv/):

Install uv (if not already installed):

```shell
# On macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or with pip
pip install uv
```

From the root of the directory, sync dependencies:

```shell
uv sync --group dev
pre-commit install --install-hooks
```

This creates a virtual environment in `.venv` and installs all dependencies.

To activate the environment (optional, `uv run` handles this automatically):

```shell
source .venv/bin/activate  # Linux/macOS
# or
.venv\Scripts\activate     # Windows
```

You are now ready to start developing.

## How to test the project

Run the full test suite:

```shell
nox
```

List the available Nox sessions:

```shell
nox --list-sessions
```

You can also run a specific Nox session. For example, invoke the unit test suite like this:

```shell
nox --session=tests
```

Unit tests are located in the [tests](https://code.usgs.gov/wma/nhgf/toolsteam/gdptools/-/tree/develop/tests?ref_type=heads) directory, and are written using the [pytest](https://pytest.readthedocs.io/) testing framework.

## How to build the documentation

```shell
nox -s docs
```

## How to submit changes

Open a [merge request](https://code.usgs.gov/wma/nhgf/toolsteam/gdptools/-/merge_requests) to
submit changes to this project.

Your pull request needs to meet the following guidelines for acceptance:

- The Nox test suite must pass without errors and warnings.
- Include unit tests. This project maintains 100% code coverage.
- If your changes add functionality, update the documentation
  accordingly.

Feel free to submit early, though---we can always iterate on this.

We use pre-commit

It is recommended to open an issue before starting work on anything.
This will allow a chance to talk it over with the owners and validate
your approach.