Development

Recipe is under active development, and contributors are welcome.

If you have a feature request, suggestion, or bug report, please open a new issue on GitHub. To submit patches, please send a pull request on GitHub.

Conventions

Recipe code wraps at 79 characters and passes flake8. Strings should single quoted unless double quoting leads to less escaping. Add tests to achieve 100% code coverage.

Source Control

The project is hosted on at https://github.com/juiceinc/recipe

The repository is publicly accessible. To check it out, run:

git clone git://github.com/juiceinc/recipe.git

Git Branch Structure

develop

The “next release” branch. Likely unstable.

master

Current production release (0.37.2) on PyPi.

Each release is tagged.

When submitting patches, please place your feature/change in its own branch prior to opening a pull request on GitHub.

Adding New Extensions

Recipe welcomes new extensions.

Extensions subclass RecipeExtension and plug into the base recipe’s .query() method which builds a SQLAlchemy query. Extensions can either modify the base recipe like these do.

  • AutomaticFilters

  • Anonymize

Or extensions can merge one or more recipes into the base recipe. Extensions that require another recipe should have a classname that ends with Recipe.

  • CompareRecipe

  • BlendRecipe

When adding an extension, do the following.

  1. Add extension to src/extensions.py

  2. Add tests to tests/test_extensions.py, cover 100% of extension function and test that the extension doesn’t interfere with other extensions

  3. Make sure your extension code passes flake8

  4. Add extension description to docs/extensions/

  5. Submit a PR!

Adding New Ingredients

Recipe welcomes new ingredients, particularly metrics and dimensions that cover common patterns of data aggregation.

Subclass the appropriate ingredient and don’t duplicate something that a superclass does. For instance WtdAvgMetric is a subclass of DivideMetric that generates it’s expressions differently.

Extra functionality can be added by using Ingredient.meta in structured ways.

A checklist of adding an extension.

  1. Add extension to src/ingredients.py

  2. Add tests to tests/test_ingredients.py, cover 100% of ingredient parameters.

  3. Make sure your ingredient passes flake8

  4. Submit a PR!

Testing Recipe

Testing is crucial to confident development and stability. This stable project is used in production by many companies and developers, so it is important to be certain that every version released is fully operational. When developing a new feature for Recipe, be sure to write proper tests for it as well.

When developing a feature for Recipe, the easiest way to test your changes for potential issues is to simply run the test suite directly.

$ make tests

This will run tests under pytest and show code coverage data.

Continuous Integration

Every commit made to the develop branch is automatically tested and inspected upon receipt with `Travis CI`_. If you have access to the main repository and broke the build, you will receive an email accordingly.

Anyone may view the build status and history at any time.

Additional reports will also be included here in the future, including PEP 8

checks and stress reports for extremely large datasets.

Building the Docs

Documentation in reStructured Text and powered by Sphinx.

The Docs live in recipe/docs. In order to build them, you will first need

to install Sphinx.

$ pip install sphinx

To build an HTML version of the docs, simply run the following from the docs directory:

$ make html

Your docs/_build/html directory will then contain the fully build documentation, ready for publishing. You can also generate the documentation in tons of other formats.

If you want to learn more, check out the API Documentation.