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 and available in /lokal-profil/COH-tools/tree/CI.

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.
.travis.yml: The connection needed for TravisCI to run the tox file.
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
.travis.yml: Can be re-used as is.
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.