FiftyOne is open source and community contributions are welcome!
If you have not already, we highly recommend browsing currently active projects to get a sense of what is planned for FiftyOne. Each project is a component of FiftyOne that we, the maintainers, deem critical to building a world-class ecosystem for building high quality CV/ML datasets and models.
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.
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.
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
developbranch - Create a pull request into the
developbranch of https://github.com/voxel51/fiftyone
The develop branch contains the bleeding edge version of FiftyOne. If you are
contributing to an existing feature branch, then make your pull requests into
that branch instead. When in doubt, work against the develop branch.
Once your pull request has been merged, your changes will be automatically included in the next FiftyOne release!
Here's some general guidelines for developing new features and patches for FiftyOne:
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
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.
To contribute any feature to FiftyOne, you must install from source, including
the -d flag to install developer dependencies, pre-commit hooks, etc:
bash install.bash -dRefer 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.
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 installTo 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>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.
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.
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.
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.