Contributing guide#

We welcome your contributions! Here you will find a guide to the contribution workflow and tips for contributing to napari. Do not hesitate to contact us if you have any queries.

Note

To contribute to our blog, the Island Dispatch, check out https://github.com/napari/island-dispatch.

Contributing workflow#

napari development occurs primarily on GitHub. If you are new to GitHub we recommend checking out the detailed Github Docs.

The first step to make changes to napari is to set up a napari development installation.

You can then use git to save your changes and open a pull-request (PR) via the following steps:

  1. Make and save your 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"

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.

  1. Share your changes:

To push the local changes in your new feature branch to your forked repository:

git push -u origin your-branch-name

Note we are pushing to the remote named ‘origin’ above. If you have followed the development installation instructions, ‘origin’ would be the name of the remote of your forked repository. If you are unsure of the name of your remotes, you can use the following command to check and ensure you are pushing to the correct remote:

git remote -vv

You can then make a PR to napari’s main branch.

napari contribution guides#

Translations#

Starting with version 0.4.7 offers the possibility of installing language packs, enabling the user interface to be displayed in different languages. This means that all user interface strings need to use the trans() helper function. See the translations guide for more.

Tests#

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

We have dedicated documentation on testing that we recommend you read as you’re working on your first contribution.

Adding icons#

If you want to add a new icon to the app, make the icon in whatever program you like and add it to napari/resources/icons/. Icons must be in .svg format.

Icons are automatically built into a Qt resource file that is imported when napari is run. If you have changed the icons and would like to force a rebuild of the resources, then you can either delete the autogenerated napari/resources/_qt_resources*.py file, or you can set the NAPARI_REBUILD_RESOURCES environmental variable to a truthy value, for example:

export NAPARI_REBUILD_RESOURCES=1

Icons are typically used inside of one of our stylesheet.qss files, with the {{ id }} variable used to expand the current theme name.

QtDeleteButton {
   image: url("theme_{{ id }}:/delete.svg");
}

Performance#

Performance related PRs should include a benchmark in order to clearly depict the use-case that is being optimized for. Ideally PRs that add a new feature should also include benchmarks to show the new feature is not too slow but this is less vital. Benchmarks provides more information on benchmarking. If you find poor performance, profiling and performance monitoring can help identify the cause and where to optimize.

API Changes#

If you are changing an existing API or adding a new one, make sure you update the corresponding docstring to contain the .. versionadded:: or .. versionchanged:: directive. For more information see the Sphinx documentation. Please also consider documenting any major features/changes in our tutorials and other usage documentation.

Contributing documentation#

See Contributing Documentation for information on how to contribute documentation.