Skip to content

Latest commit

 

History

History
99 lines (74 loc) · 3.88 KB

CONTRIBUTING.rst

File metadata and controls

99 lines (74 loc) · 3.88 KB
Raw

Contributing

contributors

Everyone is welcomed to contribute: there's even a wish list! Beginner? It's easy-ish to start! Please see this tutorial.

If you can contribute with a pull request, please do so. If not, open an issue here and someone will look into it.

Please make your contributions to the unreleased branch and make sure to write a test for it (no decrease in coverage).

Documentation

Great documentation is absolutely key in any project. Please feel free to contribute edits and additions to webchanges, especially if you're new! It is written in reStructuredText for Sphinx, and you can read a primer here.

Code

Inline code docstrings, additional test coverage, bug fixes, extension of existing functionality, new functionalities, and much more are always welcomed.

Please keep in mind PEP-20's Zen of Python when writing code:

  • Beautiful is better than ugly.
  • Explicit is better than implicit.
  • Simple is better than complex.
  • Complex is better than complicated.
  • Flat is better than nested.
  • Sparse is better than dense.
  • Readability counts.
  • Special cases aren't special enough to break the rules.
  • Although practicality beats purity.
  • Errors should never pass silently.
  • Unless explicitly silenced.
  • In the face of ambiguity, refuse the temptation to guess.
  • There should be one-- and preferably only one --obvious way to do it.
  • Although that way may not be obvious at first unless you're Dutch.
  • Now is better than never.
  • Although never is often better than right now.
  • If the implementation is hard to explain, it's a bad idea.
  • If the implementation is easy to explain, it may be a good idea.
  • Namespaces are one honking great idea -- let's do more of those!

If you are contributing a filter, please make sure that you add an example to the documentation (/docs/filters.rst) and the relevant data to /tests/data/docs_filters_testdata.yaml file to allow the example to be automatically tested by /tests/docs_filters_test.py.

Testing contributions

Testing code

You can ensure that your code contributions pass all tests by running tests locally (after installing all Python dev packages, as below) before creating a pull request, starting from the project's root directory:

pip install -U tox
tox --parallel

Alternatively, you can manually run the following commands:

pip install -U -r tests/requirements_pre-commit.txt -r tests/requirements_pytest.txt -r docs/requirements.txt
pre-commit autoupdate
pre-commit run -a
python -m pytest -v --cov --cov-report=term

All tests need to pass, and the amount of lines covered by tests should not decrease (please write new tests or update the existing ones to cover your new code!)

Testing documentation

You can build the documentation locally by using $ make html (Linux) or make_html.bat (Windows) from within the docs directory to check for errors before contributing.

Unreleased version

To install the unreleased version, please run:

pip install https://github.com/mborsetti/webchanges/archive/unreleased.tar.gz