Contributing

First of all, thanks for considering contributing code to tavolo!
Before contributing please open an issue in the Github repository explaining the module you wish to contribute.
Assuming the module is accepted, it will be tagged so in the issue opened so you can start implementing to avoid wasting contributor’s time for code that won’t be accepted.
tavolo is built to compliment the tf.keras module, make sure your contributions are focused at it.
Once your suggested module is accepted, follow the guidelines in Code and Documentation and Testing, and once completed you can open a pull request to the dev branch.

Note

Do not create pull requests into the master branch. Pull requests should be made to the dev branch, from which changes will be merged into master on releases.

Code and Documentation

tavolo is open source, viewing the source code of a module and understanding every step in its implementation should be easy and straightforward, so users can trust the module they wish to use.
To fulfill this requirement, follow these guidelines:
  1. Comments - Even if the code is clear, use comments to explain steps (step comment example).

  2. Variable verbosity - Use verbose variable names that imply the meaning of their content, e.g. use mask instead of m.

  3. Clear tensor shapes - When applying operations on tensors, include the shape of the result in a comment. (tensor shape example).

  4. Format - reStructuredText is the documentation format use, and specifically PEP 287 (PyCharm’s default) for class methods. On class level docstring, make sure you always include the following sections:

If you are contributing a tf.keras.layers.Layer subclass, also include:

Testing

Tavolo uses pytest and codecov for its testing. Make sure you write your tests to cover the full functionality of the contributed code.
The tests should be written as a separate file for each module and in the destination tests/<parent_module>/<module_name>_test.py.
For example for the module tvl.normalization.LayerNormalization, the tests should be written in tests/normalization/layer_normalization_test.py.
It is quite difficult to define in advance which tests are mandatory, but you can draw insipration from the existing modules.
In the specific case of tf.keras.layers.Layer implementation, always include:
  1. test_shapes() - Given accepted input shapes, make sure the output shape is as expected (test_shapes() example).

  2. test_masking() - Make sure layer supports masking (test_masking() example).

  3. test_serialization() - Make sure layer can be saved and loaded using get_config and from_config (test_serialization() example).

If possible, also include test_logic() for evaluating expected output given known input (test_logic() example).

When done, run tests locally to make sure everything works fine, to do so, make sure you have installed the test requirements from the requirements/test.py file and run tests locally using the following command from the main directory
pytest --cov=tavolo tests/
Strive for 100% coverage, and if all is well, create a pull request (to the dev branch) and it will be added to the package in a following release.