CONTRIBUTING.md

Contributing Guide

We welcome your contributions! Please see the provided steps below and never hesitate to contact us.

If you are a new user, we recommend checking out the detailed Github Guides.

Setting up a development installation

In order to make changes to napari-metadata, you will need to fork the repository.

If you are not familiar with git, we recommend reading up on this guide.

Clone the forked repository to your local machine and change directories:

git clone https://github.com/your-username/napari-metadata.git
cd napari-metadata

Set the upstream remote to the base napari-metadata repository:

git remote add upstream https://github.com/napari/napari-metadata.git

Install the package in editable mode, along with all of the developer tools using uv:

uv pip install -e . --group dev

Or equivalently with pip:

pip install -e . --group dev

We use pre-commit hooks to format and lint code automatically prior to each commit. The hooks are configured in .pre-commit-config.yaml and run ruff for formatting and linting, among other checks.

We recommend using prek, a faster drop-in replacement for pre-commit written in Rust with no Python runtime dependency. prek is included with the development dependencies. Register the git hooks with:

prek install

Upon committing, your code will be formatted and linted according to our ruff configuration. To learn more, see ruff's documentation.

You can run all hooks against the entire codebase at any time:

prek run --all-files

If you wish to tell the linter to ignore a specific line use the # noqa comment along with the specific error code (e.g. import sys # noqa: E402) but please do not ignore errors lightly.

Making changes

Create a new feature branch:

git checkout main -b your-branch-name

git will automatically detect changes to a repository. You can view them with:

git status

Add and commit your changed files:

git add my-file-or-directory
git commit -m "my message"

Tests

We use unit tests to ensure that napari-metadata works as intended. Writing tests for new code is a critical part of keeping napari-metadata maintainable as it grows.

Run tests using tox (which uses uv under the hood via tox-uv):

uvx --with tox-gh-actions tox

Or run pytest directly after installing development dependencies:

pytest

Help us make sure it's you

Each commit you make must have a GitHub-registered email as the author. You can read more here.

To set it, use git config --global user.email your-address@example.com.

Keeping your branches up-to-date

Switch to the main branch:

git checkout main

Fetch changes and update main:

git pull upstream main --tags

This is shorthand for:

git fetch upstream main --tags
git merge upstream/main

Update your other branches:

git checkout your-branch-name
git merge main

Sharing your changes

Update your remote branch:

git push -u origin your-branch-name

You can then make a pull-request to napari-metadata's main branch.

Building the docs

Install pixi, then from the project root:

pixi run docs-build

The docs will be built at docs/_build. Most web browsers will also allow you to preview HTML pages directly. Try entering file:///absolute/path/to/napari-metadata/docs/_build/index.html in your address bar.

You can preview with a live-reloading server that opens automatically:

pixi run docs-live

Code of conduct

napari has a Code of Conduct that should be honored by everyone who participates in the napari community, including napari-metadata.

Questions, comments, and feedback

If you have questions, comments, suggestions for improvement, or any other inquiries regarding the project, feel free to open an issue.

Issues and pull-requests are written in Markdown. You can find a comprehensive guide here.