Skip to content

Latest commit

 

History

History
238 lines (179 loc) · 8.69 KB

CONTRIBUTING.md

File metadata and controls

238 lines (179 loc) · 8.69 KB

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, 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.git
$ cd napari

Set the upstream remote to the base napari repository:

$ git remote add upstream https://github.com/napari/napari.git

Install the required dependencies:

$ pip install -r requirements.txt

Make the development version available globally:

$ pip install -e .

We use pre-commit to run black formatting and flake8 linting automatically prior to each commit. Please install it in your environment as follows:

$ pre-commit install

Upon committing, your code will be formatted according to our black configuration, which includes the settings skip-string-normalization = true and max-line-length = 79. To learn more, see black's documentation.

Code will also be linted to enforce the stylistic and logistical rules specified in our flake8 configuration, which currently ignores E203, E501, W503 and C901. For information on any specific flake8 error code, see the Flake8 Rules. You may also wish to refer to the PEP 8 style guide.

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.

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 {{ folder }} variable used to expand the current theme name.

QtDeleteButton {
   image: url(":/themes/{{ folder }}/delete.svg");
}

Creating and testing themes

A theme is a set of colors used throughout napari. See, for example, the builtin themes in napari/utils/theme.py. To make a new theme, create a new dict in palettes with the same keys as one of the existing themes, and replace the values with your new colors. To test out the theme, use the theme_sample.py file from the command line as follows:

python -m napari._qt.theme_sample

note: you may specify a theme with one additional argument on the command line:

python -m napari._qt.theme_sample dark

(providing no arguments will show all themes in theme.py)

Making changes

Create a new feature branch:

$ git checkout master -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"

Running Tests

To run our test suite locally, install test requirements and run pytest as follows:

pip install -r requirements/test.txt
pytest

Writing Tests

Writing tests for new code is a critical part of keeping napari maintainable as it grows. Tests are written in files whose names begin with test_* and which are contained in one of the _tests directories.

There are a couple things to keep in mind when writing a test where a Qt event loop or a napari.Viewer is required. The important thing is that any widgets you create during testing are cleaned up at the end of each test:

  1. If you need a QApplication to be running for your test, you can use the qtbot fixture from pytest-qt

    note: fixtures in pytest can be a little mysterious, since it's not always clear where they are coming from. In this case, using a pytest-qt fixture looks like this:

    # just by putting `qtbot` in the list of arguments
# pytest-qt will start up an event loop for you
def test_something(qtbot):
    ...

    qtbot provides a convenient addWidget method that will ensure that the widget gets closed at the end of the test. It also provides a whole bunch of other convenient methods for interacting with your GUI tests (clicking, waiting signals, etc...). See the qtbot docs for details.

    # the qtbot provides convenience methods like addWidget
def test_something_else(qtbot):
    widget = QWidget()
    qtbot.addWidget(widget)  # tell qtbot to clean this widget later
    ...

  2. When writing a test that requires a napari.Viewer object, we provide our own convenient fixture called viewer_factory that will take care of creating a viewer and cleaning up at the end of the test. When using this function, it is not necessary to use a qtbot fixture, nor should you do any additional cleanup (such as using qtbot.addWidget or calling viewer.close()) at the end of the test. Duplicate cleanup may cause an error. Use the factory as follows:

    # the viewer_factory fixture is defined in napari/conftest.py
def test_something_with_a_viewer(viewer_factory):
    # viewer factory takes any keyword arguments that napari.Viewer() takes
    view, viewer = viewer_factory()
    # note, `view` here is just a pointer to viewer.window.qt_viewer

    # do stuff with the viewer, no qtbot or viewer.close() methods needed.
    ...

If you're curious to see the actual viewer_factory fixture definition, it's in napari/conftest.py

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 [email protected].

Keeping your branches up-to-date

Switch to the master branch:

$ git checkout master

Fetch changes and update master:

$ git pull upstream master --tags

This is shorthand for:

$ git fetch upstream master --tags
$ git merge upstream/master

Update your other branches:

$ git checkout your-branch-name
$ git merge master

Sharing your changes

Update your remote branch:

$ git push -u origin your-branch-name

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

Building the docs

From the project root:

$ make docs

The docs will be built at docs/build/html.

Most web browsers will allow you to preview HTML pages. Try entering file:///absolute/path/to/napari/docs/build/html/index.html in your address bar.

Code of conduct

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

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.