Guide

Development Guide

How to contribute and build the library

Overview

This page explains how to set up a local development environment, build the library from source, and contribute changes back to the project. Whether you are fixing a bug, adding a feature, or improving documentation, following these guidelines ensures your contribution integrates smoothly with the rest of the codebase and passes the automated checks that run on every pull request.

Prerequisites

Before you begin, make sure you have the following:

Python 3.0 or later — required by setup.py
pip (or pip3) — for installing build and formatting tools
Git — for cloning the repository and managing branches
setuptools ≥ 42 and wheel — the build backend declared in pyproject.toml
numpy ≥ 1 — the only runtime dependency; installed automatically when you install the package
black — the project's code formatter (installed separately; see Style guide)
A configured Git identity (user.name and user.email) so that DCO sign-offs work correctly
Optionally, access to Seek Thermal camera hardware for end-to-end testing of sample applications

Installation

Follow these steps to install the library in development mode so that edits to the source are immediately reflected without reinstalling.

Clone the repository

git clone https://github.com/seekthermal/seekcamera-python.git
cd seekcamera-python

Create and activate a virtual environment (recommended)

python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

Install the package in editable mode with its dependencies
```
pip3 install -e .
```
This installs seekcamera-python and automatically pulls in numpy.
Install the code formatter
```
pip3 install black
```
Verify the installation
```
python3 -c "import seekcamera; print('seekcamera imported successfully')"
```
A clean import with no errors confirms the library is installed correctly.

Configuration

The build system is configured in two files at the repository root.

`pyproject.toml`

Declares the build backend and its minimum requirements. You should not need to edit this file unless you are changing the build system itself.

Key	Value	Effect
`requires`	`["setuptools>=42", "wheel"]`	Tools that must be present before `setup.py` runs
`build-backend`	`setuptools.build_meta`	Tells pip which backend to use when building distributions

`setup.py`

Controls the package metadata and what gets installed. Key fields relevant to contributors:

Field	Current value	Notes
`version`	`1.3.0`	Updated on each release following `[major].[minor].[patch]`
`python_requires`	`>=3.0`	Do not lower this constraint without discussion
`install_requires`	`["numpy>=1"]`	Add new runtime dependencies here if your contribution needs them
`data_files`	`examples/`	Both sample scripts are shipped with the package

If your contribution introduces a new example script, add it to the data_files list in setup.py so it is included in distributions.

Usage

Branching workflow

All contributions start from the main branch, which is the top-of-tree branch where release tags are created.

Sync your local main
```
git checkout main
git pull
```
Create a feature branch
```
git checkout -b feature-my-change
```
Use a short, descriptive name that reflects what the branch does.
Make commits with DCO sign-off

Every commit must be signed off to comply with the Developer Certificate of Origin. Use the -s flag:
```
git commit -s
```
This appends a Signed-off-by: Your Name <you@example.com> line to the commit message automatically, provided your Git user.name and user.email are configured. Write commit messages in clear, imperative language (e.g., Add sharpening filter API wrapper).
Keep a long-lived branch up to date

If main moves forward while you are working, merge it in using --no-ff to preserve history:
```
git pull
git checkout feature-my-change
git merge --no-ff origin/main
```
Push your branch
```
git push -u origin feature-my-change
```

Style guide

The project uses black for uniform formatting. Run it before every commit:

black .

A GitHub Actions workflow checks formatting automatically when you open a pull request. Failing this check will block the PR from merging.

Pull request checklist

Before opening a PR against main, confirm that you have:

Written a clear, imperative description of what changed and why
Added or updated docstrings on any public methods you modified
Tested all sample applications (note the hardware you used in the PR description)
Included any additional unit tests where appropriate
Run black . and confirmed formatting passes
Signed every commit with git commit -s
Resolved any merge conflicts with main

Examples

Format and validate code before committing

Run black from the repository root to auto-format all Python files:

black .

Expected output (first run with changes):

reformatted seekcamera/somefile.py
All done! ✨ 🍰 ✨
1 file reformatted.

Expected output when everything is already compliant:

All done! ✨ 🍰 ✨
1 file left unchanged.

Create a signed commit

After staging your changes, commit with the DCO sign-off flag:

git add seekcamera/myfeature.py
git commit -s -m "Add wrapper for new sharpening filter API"

The resulting commit message will include:

Add wrapper for new sharpening filter API

Signed-off-by: Jane Doe <jane.doe@example.com>

Build a distribution package

To produce a wheel and source distribution (for example, to test packaging locally):

pip3 install build
python3 -m build

Expected output (abbreviated):

Successfully built seekcamera-python-1.3.0.tar.gz and seekcamera_python-1.3.0-py3-none-any.whl

The artifacts appear in the dist/ directory.

Troubleshooting

Black reports formatting errors in CI but not locally

Symptom: The GitHub Actions formatting check fails, but running black . locally reports no changes.

Likely cause: You are running a different version of black than the one used in CI.

Fix: Pin your local black version to match CI, or run pip3 install --upgrade black to ensure you are on the latest release. Re-run black . and commit any resulting changes.

DCO bot blocks the pull request

Symptom: The Probot DCO check fails and the PR cannot be merged.

Likely cause: One or more commits are missing the Signed-off-by line.

Fix: Amend the most recent commit if it is the only unsigned one:

git commit --amend -s
git push --force-with-lease origin feature-my-change

If multiple commits are unsigned, follow the instructions the DCO bot posts in the PR comments. These typically involve an interactive rebase to add sign-offs retroactively.

`pip install -e .` fails with a setuptools error

Symptom: Installation in editable mode raises an error referencing setuptools or wheel.

Likely cause: Your local setuptools is older than version 42 (the minimum declared in pyproject.toml).

Fix:

pip3 install --upgrade setuptools wheel
pip3 install -e .

Merge conflicts with `main`

Symptom: Git reports conflicts after pulling from main into your feature branch.

Likely cause: Concurrent changes were merged into main while your branch was in progress.

Fix: Resolve conflicts manually, mark them resolved, and complete the merge:

# After editing conflicting files
git add <resolved-files>
git commit -s

If you are unsure how to resolve a specific conflict, note it in your PR and the maintainers can assist.