Developer guidelines/CI for python

The below assumes a repo using python3 only and some of the instructions are aimed for repos on GitHub. Note that the underlying tox infrastructure can still be run locally even without GitHUb/Travis

This document also exists at phab:T159116

Basic settings have been done for

Files:

As an example we will use some quite basic settings developed for COH-tools.

tox.ini

Main entrypoint specifying python version to use, and tests and linting to run.

setup.cfg

Specific settings for nosetests mostly to do with coverage.

requirements.txt

The dependencies needed to run the program. Install these using pip3 install -r requirements.txt (possibly with the --process-dependency-links flag).

requirements-test.txt

The additional dependencies needed to run the tests.

Notes on files:

tox.ini

I've set pydocstyle to ignore D100-D103 errors (missing docstrings). These shouldn't be blockers for now but docstrings should be added whenever a function is updated/added. The long term goal is to not ignore these errors and local linting might wish to have these enabled. As adding your own ignores block the default ones I've also had to add D203 and D212.

I've set flake8 to ignore E501 errors (too long lines). These shouldn't be blockers for now but strings should be fixed whenever a function is updated/added. The long term goal is to not ignore these errors and local linting might wish to have these enabled. For individual exceptions (such as long urls) use the following comment at the end of the line: # noqa: E501.

setup.cfg

Without a proper package setup the output isn't ideal. Might consider adding cover-no-print when packages are not available and cover-inclusive when they are?

requirements.txt

We include mwparserfromhell here since pywikibot silently changes it behaviour (for the worse) if it is not available.

Note that we connect to the master branch of pywikibot (not the PyPi release) and to a specific release of WikidataStuff.

requirements-test.txt

The first line (-r requirements.txt) ensures that the normal dependencies are also installed.

Re-use of files:

tox.ini

The file can be largely reused as is with the exception for [flake8] > filename, [pydocstyle] > match-dir and any unneeded ignores.

setup.cfg

Can be re-used as is with the exception of cover-package

requirements.txt

Will need to be rebuilt for each repo.

requirements-test.txt

Can be re-used as is (but may need to be extended at a later stage).

Connections:

I make connections to two services which will later vote on any PRs (and commits) allowing me to do some initial improvements before passing the PR on for review.

• I added the repo to my travis-ci.org account and enabled the "Build only if .travis.yml is present" setting. Since my TravisCI account is hooked up to my Github account it automatically added the hook to Settings > Integrations & services > Services (in GitHub).
• I also added the repo to my quantifiedcode.com account. Again since it's connected to my Github account it automatically added the hook to Settings > Webhooks (in GitHub). I normally rely on quantifiedcode to warn me about undesired (but not strictly wrong) behaviour. It is also useful to ensure you don't introduce new problems (such as missing docstrings) in a PR. Its detection algorithm isn't perfect though so I tend to use it as a recommendation rather than a blocker.

Notes on connections:

TravisCI

The first couple of runs will allow you to identify if any dependencies are missing from requirements.txt (in the tox_env=py3 log)

quantifiedcode

You can adjust the settings further by going to Settings > Webhooks and clicking the quantified code link. Specifically you can make it just trigger on PRs etc.