Contributing to FiftyOne

FiftyOne is open source and community contributions are welcome!

If you haven’t already, we highly recommend reviewing the contribution guide to get a sense of how you can get involved with FiftyOne. There are many ways to contribute, including reporting bugs, improving documentation, enhancing existing code, or helping the community through reviews and discussions.

Don't be intimidated by the procedures outlined below. They are not dogmatic and are only meant to help guide development as the project and number of contributors grow.

Contribution Process

GitHub Issues

The FiftyOne contribution process generally starts with filing a GitHub issue.

FiftyOne defines four categories of issues: feature requests, bug reports, documentation fixes, and installation issues. Details about each issue type and the issue lifecycle are discussed in our issue policy. Small tweaks such as typos or other small improvements do not need to have a corresponding issue.

FiftyOne maintainers actively triage and respond to GitHub issues. In general, we recommend waiting for feedback from a FiftyOne maintainer or community member before proceeding to implement a feature or patch. This is particularly important for significant changes, and will typically be labeled during triage with needs design.

Pull Requests

After you have agreed upon an implementation strategy for your feature or patch with a FiftyOne maintainer, the next step is to introduce your changes (see developer guide) as a pull request against the FiftyOne repository.

Steps to make a pull request:

• Fork https://github.com/voxel51/fiftyone
• Implement your feature as a branch off of the develop branch
• Create a pull request into the develop branch of https://github.com/voxel51/fiftyone

If you are not a Voxel51 team member, we recommend opening your pull request against the community branch (see below).

Community pull requests

If you are not a Voxel51 team member, open your pull request against the community branch rather than develop. If you open one against develop or a release branch, it is automatically retargeted to community for you.

Your changes are unaffected by the retarget. Whenever community is ahead of develop, a community → develop pull request is opened automatically for a maintainer to review and merge, so your contribution still lands in develop — it just goes through community first.

Once your pull request has been merged, your changes will be automatically included in the next FiftyOne release!

Contribution Guidelines

Here's some general guidelines for developing new features and patches for FiftyOne:

Write designs for significant changes

For significant changes to FiftyOne, we recommend outlining a design for the feature or patch (in the GitHub issue itself) and discussing it with a FiftyOne maintainer before investing heavily in implementation.

During issue triage, we try to proactively identify issues that require design by labeling them with needs design. This is particularly important if your proposed implementation:

• Introduces new user-facing FiftyOne APIs
  • FiftyOne's API surface is carefully designed to generalize across a variety of common CV/ML use cases. It is important to ensure that new APIs are broadly useful to CV/ML engineers and scientists, easy to work with, and simple yet powerful
• Adds new library dependencies to FiftyOne
• Makes changes to critical internal abstractions

Make changes backwards compatible

FiftyOne's users rely on specific App and Core behaviors in their daily workflows. As new versions of FiftyOne's are developed and released, it is important to ensure that users' workflows continue to operate as expected. Accordingly, please take care to consider backwards compatibility when introducing changes to the FiftyOne codebase. If you are unsure of the backwards compatibility implications of a particular change, feel free to ask a FiftyOne maintainer or community member for input.

Developer Guide

Installation

To contribute any feature to FiftyOne, you must install from source, including the -d flag to install developer dependencies, pre-commit hooks, etc:

# Mac or Linux
bash install.sh -d

# Windows
.\install.bat -d

Refer to the main README to make sure you have the necessary system packages installed on your machine.

If you are making a change to the FiftyOne App, refer to the App README for development instructions.

Pre-commit hooks

Performing a developer install per the above instructions will install some pre-commit hooks that will automatically apply code formatting before allowing you to create a git commit.

See .pre-commit-config.yaml for the definitions of our hooks.

To manually install our pre-commit hooks, simply run:

pre-commit install

To manually lint a file, run the following:

# Manually run linting configured in the pre-commit hook
pre-commit run --files <file>

Note that the pylint component of the pre-commit hook only checks for errors. To see the full output, run:

pylint <file>

Python API

The FiftyOne API is implemented in Python and the source code lives in fiftyone/fiftyone. Refer to setup.py to see the Python versions that the project supports.

All Python code contributed to FiftyOne must follow our style guide.

FiftyOne App

The FiftyOne App is an Electron App implemented in TypeScript and the source code lives in fiftyone/app.

All App code contributed to FiftyOne must follow our style guide.

Documentation

The FiftyOne Documentation is written using Sphinx and Sphinx-Napoleon and the source code lives in fiftyone/docs.

When adding a new feature to FiftyOne or changing core functionality, be sure to update both the docstrings in source code and the corresponding documentation in all relevant locations.

All documentation, including RST and all code samples embedded in it, must follow our style guide.

Tests

FiftyOne has a suite of tests in fiftyone/tests.

These tests are automatically run on any PRs into the develop branch, and all tests must pass in order for the branch to be mergeable.

Please be sure to write tests when you add new features.