How To Contribute
First of all, thank you for considering contributing to
The intent of this document is to help get you started.
Don’t be afraid to reach out with questions – no matter how “silly.”
Just open a PR whether you have made any significant changes or not, and we’ll try to help. You can also open an issue to discuss any changes you want to make before you start.
Contributions of any size are welcome! Fixed a typo? Changed a docstring? No contribution is too small.
Try to limit each pull request to one change only.
Always add tests and docs for your code.
Make sure your proposed changes pass our CI. Until it’s green, you risk not getting any feedback on it.
Once you’ve addressed review feedback, make sure to bump the pull request with a comment so we know you’re done.
Local Dev Environment
To start, create a virtual environment and activate it. If you don’t already have a preferred way of doing this, you can take a look at some commonly used tools: pew, virtualfish, and virtualenvwrapper.
Next, get an up to date checkout of the
mwsql repository via
$ git clone firstname.lastname@example.org:blancadesal/mwsql.git
or if you want to use git via
$ git clone https://github.com/blancadesal/mwsql.git
Change into the newly created directory and install an editable version of
$ cd mwsql $ pip install -e .
pip will install all the necessary dependencies for you, no need to install from a separate
The only dependency you really need to install is tox. It will handle everyhing else for you, including running tests, formatting and linting through pre-commit, and building and serving the latest version of the documentation. Below are a few examples of how to run tox:
$ tox # This will run the full pytest suite, as well as pre-commit. # These are the same tests that are run by the CI $ tox -e pre-commit # This will run the pre-commit linting and formatting checks $ tox -e docs # This will run the documentation build process $ tox -e serve-docs # Live-serve docs with Sphinx autobuild
We use flake8 to enforce PEP 8 conventions, isort to sort our imports, and we use the black formatter with a line length of 88 characters. Static typing is enforced using mypy. Code that does not follow these conventions won’t pass our CI. These tools are configured in either
Make sure your docstrings are formatted using the Sphinx-style format like in the example below:
def add_one(number: int) -> int: """ Add one to a number. :param number: A very important parameter. :type number: int :rtype: int """
As long as you run the tox suite before submitting a PR, you should be fine. Tox runs all the tools above by calling pre-commit. It also runs the whole pytest suite (see Tests below) across all supported Python versions, the same as the CI workflow.
See the section above how to run pre-commit on its own via tox
We use pytest for testing. For the sake of consistency, write your asserts as
actual == expected:
def test_add_one(): assert func(2) == 3 assert func(4) == 5
You can run the test suite either through tox or directly with pytest:
$ python -m pytest
Use semantic newlines in
.rstfiles (reStructuredText files):
This is a sentence. This is another sentence.
If you start a new section, add two blank lines before and one blank line after the header, except if two headers follow immediately after each other:
Last line of previous section. Header of New Top Section ------------------------- Header of New Section ^^^^^^^^^^^^^^^^^^^^^ First line of new section.
If you add a new feature, include one or more usage examples in