Skip to content

Latest commit

 

History

History
155 lines (98 loc) · 4.69 KB

CONTRIBUTING.rst

File metadata and controls

155 lines (98 loc) · 4.69 KB
Raw

How To Contribute

First of all, thank you for considering contributing to mwsql! 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.

Basic Guidelines

  • 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, install Poetry. Poetry will handle the creation of the virtual environment and the installation of the dependencies for you.

Next, get an up to date checkout of the mwsql repository via SSH:

$ git clone [email protected]:blancadesal/mwsql.git

or if you want to use git via https:

$ git clone https://github.com/blancadesal/mwsql.git

Change into the newly created directory and install the dependencies using Poetry:

$ cd mwsql
$ poetry install

Poetry will install all the necessary dependencies for you, no need to install from a separate requirements.txt file.

Dev dependencies

The only dependency you really need to install is tox. It will handle everything 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

Code style

  • We use ruff for linting and formatting Python code. Static typing is enforced using mypy. Code that does not follow these conventions won't pass our CI. These tools are configured in either tox.ini or pyproject.toml.
  • 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.
$ tox
  • See the section above how to run pre-commit on its own via tox

Tests

  • 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

Docs

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 examples.rst.