Skip to main content
Version: 0.15.50

How to contribute a Custom Expectation to Great Expectations

This guide will help you contribute your Custom Expectations to Great Expectations’ shared library. Your Custom Expectation will be featured in the Expectations Gallery, along with many others developed by data practitioners from around the world as part of this collaborative community effort.

Prerequisites: This how-to guide assumes you have:

Steps​

1. Verify that your Custom Expectation is ready for contribution​

We accept contributions into the Great Expectations codebase at several levels: Experimental, Beta, and Production. The requirements to meet these benchmarks are available in our document on levels of maturity for Expectations.

If you call the print_diagnostic_checklist() method on your Custom Expectation, you should see a checklist similar to this one: 

✔ Has a valid library_metadata object
✔ Has a docstring, including a one-line short description
  ...
✔ Has at least one positive and negative example case, and all test cases pass
✔ Has core logic and passes tests on at least one Execution Engine
  ...
✔ Passes all linting checks
✔ Has basic input validation and type checking
✔ Has both statement Renderers: prescriptive and diagnostic
✔ Has core logic that passes tests for all applicable Execution Engines and SQL dialects
  ...
  Has a full suite of tests, as determined by project code standards
  Has passed a manual review by a code owner for code standards and style guides

If you've satisfied at least the first five checks, you're ready to make a contribution!

info

Not quite there yet? See our guides on creating Custom Expectations for help!

For more information on our code standards and contribution, see our guide on Levels of Maturity for Expectations.

2. Double-check your Library Metadata​

We want to verify that your Custom Expectation is properly credited and accurately described.

Ensure that your Custom Expectation's library_metadata has the following keys, and verify that the information listed is correct:

  • contributors: You and anyone else who helped you create this Custom Expectation.
  • tags: These are simple descriptors of your Custom Expectation's functionality and domain (statistics, flexible comparisons, geography, etc.).
  • requirements: If your Custom Expectation relies on any third-party packages, verify that those dependencies are listed here.
Packages?
Great Expectations maintains a number of Custom Expectation Packages, containing thematically related Custom Expectations. These packages can be explored in the contrib directory of Great Expectations, and can be found on PyPI. Your Custom Expectation may fit one of these packages; if so, we encourage you to contribute your Custom Expectation directly to one of these packages.

Not contributing to a specific package? Your Custom Expectation will be automatically published in the PyPI package great-expectations-experimental. This package contains all of our Experimental community-contributed Custom Expectations not submitted to another extant package, and is separate from the core great-expectations package.

3. Open a Pull Request​

You're ready to open a Pull Request!

As a part of this process, we ask you to:

  • Sign our Contributor License Agreement (CLA)
  • Provide some information for our reviewers to expedite your contribution process, including:
    • A [CONTRIB] tag in your title
    • Titling your Pull Request with the name of your Custom Expectation
    • A brief summary of the functionality and use-cases for your Custom Expectation
    • A description of any previous discussion or coordination related to this Pull Request
  • Update your branch with the most recent code from the Great Expectations main repository
  • Resolve any failing tests and merge conflicts

Congratulations!
🎉 You've submitted a Custom Expectation for contribution to the Great Expectations codebase! 🎉

info

Contributing as a part of a Great Expectations Hackathon?

Submit your PR with a [HACKATHON] tag in your title instead of [CONTRIB], and be sure to call out your participation in the Hackathon in the text of your PR as well!

4. Stay involved!​

Once your Custom Expectation has been reviewed by a Great Expectations code owner, it may require some additional work before it is approved. For example, if you are missing required checks in your diagnostic checklist, have failing tests, or have an error in the functionality of your Custom Expectation, we will ask you to resolve these before moving forward.

If you are submitting a Custom Expectation for acceptance at a Production level, we will additionally require that you work with us to bring your Custom Expectation up to our standards for testing and code style on a case-by-case basis.

Once your Custom Expectation has passing tests and an approving review from a code owner, your contribution will be complete, and your Custom Expectation will be included in the next release of Great Expectations.

Keep an eye out for an acknowledgement in our release notes, and welcome to the community!

note

If you’ve included your (physical) mailing address in the Contributor License Agreement, we’ll send you a personalized Great Expectations mug once your first PR is merged!