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.
Add extension to src/extensions.py
Add tests to tests/test_extensions.py, cover 100% of extension function and test that the extension doesn’t interfere with other extensions
Make sure your extension code passes flake8
Add extension description to docs/extensions/
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.
Add extension to src/ingredients.py
Add tests to tests/test_ingredients.py, cover 100% of ingredient parameters.
Make sure your ingredient passes flake8
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.