Contributing

All contributions to this project are welcome via pull request (PR) on the Github repository

Issues

Please open an Issue and describe the contribution you’d like to make before submitting any code. This prevents duplication of effort and makes reviewing the eventual PR much easier for the maintainers.

Commits

Please try to use commit messages that give a meaningful history for anyone using git’s log features. Try to use messages that complete the sentence, “This commit will…” There is some excellent guidance on the subject from Chris Beams

Please ensure that your commits do not include changes to either anvil.yaml or .anvil_editor.yaml.

Components

All the components in the library are intended to work from the anvil toolbox as soon as the dependency has been added to an application, without any further setup. This means that they cannot use any of the features within the library’s theme.

If you are thinking of submitting a new component, please ensure that it is entirely standalone and does not require any css or javascript from within a theme element or native library.

If your component has custom properties or events, it must be able to cope with multiple instances of itself on the same form. There are examples of how to do this using a unique id in several of the existing components.

Whilst canvas based components will be considered, the preference is for solutions using standard Anvil components, custom HTML forms and css.

Python Code

Please try, as far as possible, to follow PEP8.

Use the Black formatter to format all code and the isort utility to sort import statements.

Add the licence text and copyright statement to the top of your code.

Ensure that there is a line with the current version number towards the top of your code.

This can be automated by using pre-commit. To use pre-commit, first install pre-commit with pip and then run pre-commit install inside your local anvil-extras repository. All commits thereafter will be adjusted according to the above anvil-extras python requirements.

Documentation

Please include documentation for your contribution as part of your PR. Our documents are written in reStructuredText and hosted at Read The Docs

Our docs are built using Sphinx which you can install locally and use to view your work before submission. To build a local copy of the docs in a ‘build’ directory:

sphinx-build docs build

You can then open ‘index.html’ from within the build directory using your favourite browser.

Testing

The project uses the Pytest library and its test suite can be run with:

python -m pytest

We appreciate the difficulty of writing unit tests for Anvil applications but, if you are submitting pure Python code with no dependency on any of the Anvil framework, we’ll expect to see some additions to the test suite for that code.

Merging

We require both maintainers to have reviewed and accepted a PR before it is merged.

If you would like feedback on your contribution before it’s ready to merge, please create a draft PR and request a review.