Contributing to CA Biositing

Thank you for your interest in contributing to CA Biositing! This guide provides step-by-step instructions to set up the project locally. Follow these guidelines to get started.

Read our Code of Conduct to keep our community approachable and respectable.

Pull Requests

We welcome contributions! Please follow these guidelines when submitting a Pull Request:

It may be helpful to review this tutorial on how to contribute to open source projects. A typical task workflow is:
Fork the code repository specified in the task and clone it locally.
Review the repo's README.md and CONTRIBUTING.md files to understand what is required to run and modify this code.
Create a branch in your local repo to implement the task.
Commit your changes to the branch and push it to the remote repo.
Create a pull request, adding the task owner as the reviewer.
Please follow the Conventional Commits naming for pull request titles.

Your contributions make this project better—thank you for your support! 🚀

Development

General Workflow

Set up your development environment with pixi install.
Install pre-commit hooks with pixi run pre-commit-install.
Create a feature branch.
Make your changes and ensure tests and pre-commit checks pass. . Submit a pull request.

Configuring Pre-commit

PRs will fail style and formatting checks as configured by pre-commit, but you can set up your local repository such that precommit runs every time you commit. This way, you can fix any errors before you send out pull requests!!

To do this, install Pixi using either the instructions on their website, or the commands below:

macOS/Linux:

curl -fsSL https://pixi.sh/install.sh | sh

Windows:

powershell -ExecutionPolicy ByPass -c "irm -useb https://pixi.sh/install.ps1 | iex"

Configure Pre-commit to run on every commit

Then, once Pixi is installed, run the following command to set up pre-commit checks on every commit

pixi run pre-commit-install

Manually run pre-commit on non-committed files

pixi run pre-commit

Manually run pre-commit on all files

pixi run pre-commit-all

Available Pixi Environments

default: Basic execution environment.
gis: Environment for GIS-related work

To activate one of these environments, run the following command:

pixi shell -e <environment>

Database and Model Development

This project uses SQLModel for database models and Alembic for migrations. Models are hand-written classes organized in src/ca_biositing/datamodels/ca_biositing/datamodels/models/.

Making Schema Changes

Edit or add SQLModel classes in the appropriate models/ subdirectory.
If adding a new model, re-export it in models/__init__.py.
Ensure services are running: pixi run start-services.

Auto-generate a migration:

pixi run migrate-autogenerate -m "Description of changes"

Review the generated migration in alembic/versions/.
Apply the migration:
```
pixi run migrate
```

Refreshing Materialized Views

After loading new data into the database, refresh the analytical views:

pixi run refresh-views

Importing Models

All models are re-exported from ca_biositing.datamodels.models:

from ca_biositing.datamodels.models import Resource, FieldSample, Place

Running Tests

This project uses pytest as its testing framework. You can execute the following command to run the full test suite:

pixi run test

This command executes python -m pytest -ra --cov=ca_biositing, which:

Runs all tests in the tests/ directory.
Shows a short test summary (-ra).
Generates coverage reports for the src/ca_biositing package.

Running Tests with Coverage

To run tests with coverage, use the following command

pixi run test-cov

This will run tests with coverage and generate an html report of said coverage.