Getting Started¶

This page walks you through setting up a development environment for TanagerSpec, running the common development tasks, and contributing changes back to the package.

Once you understand the workflow here, read the Architecture and Source Layout pages to learn how the package is structured and where new code should live.

Setting up the development environment¶

This package uses uv for dependency management and virtual environment handling.

Clone the repository:

git clone <repository-url>
cd hyperspec

Install uv (if it is not already installed on your system):

pip install uv

Create a virtual environment and install all developer dependencies:

uv sync --extra all

You are now ready to start developing TanagerSpec.

Common development tasks¶

Running tests¶

Run the test suite with:

uv run pytest

Linting and formatting¶

Check code style with Ruff:

uv run ruff check src

Format the code with Ruff:

uv run ruff format src

Building and serving documentation¶

Install the documentation dependencies and preview the site locally:

uv sync --extra docs
uv run mkdocs serve

Build the static HTML documentation:

uv run mkdocs build

Adding and updating dependencies¶

Add a new runtime dependency:

uv add package-name

Add a development dependency:

uv add --group dev package-name

Running Jupyter notebooks¶

Jupyter notebooks are a great way to explore and prototype new features. Launch JupyterLab inside your development environment with:

uv run jupyter lab

Proposing changes¶

With your environment set up, you are ready to contribute changes to the package.

Creating a new branch¶

Before starting new work, make sure you have the latest version of the source:

git checkout main
git pull upstream main

Then create a new branch with a name of your choice:

git branch NAME-OF-YOUR-BRANCH
git checkout NAME-OF-YOUR-BRANCH

Making changes¶

Modify the source files as needed. When you are happy with a change, commit it to your local repository:

git add FILE-YOU-ADDED-OR-MODIFIED
git commit -m "Short description of the changes"

When adding a feature, follow the guidance in Source Layout on where to implement it and how to expose it through a namespace.

Running tests and formatting checks¶

Before submitting, make sure all tests pass and the code is properly formatted:

uv run pytest
uv run ruff check src

Submitting a merge request¶

Finally, push your branch to the upstream repository:

git push origin NAME-OF-YOUR-BRANCH

Visit the source code repository after pushing. You should see a button to open a merge request, click it and submit.

Contribution guidelines¶

When contributing, please follow these guidelines:

Follow PEP 8 and use type hints where possible.
Add or update tests for new features and bug fixes (see tests/, with HDF5 fixtures in tests/data/tanager/).
Update the documentation as needed, including the API Reference for any user-visible API changes.