Developer guide

Project decisions

Git stashing is not user-friendly and should not be relied upon. Stashing only certain files or hunks can be done with git stash -p but that doesn’t work for new files. git add and git add -i are much friendlier. Other unfinished changes can be left behind on a separate branch. (See also: stack overflow thread and this blog post) By consequence we must allow committing only part of the working directory. We can still require a clean directory before release however.

Warn on a poorly formatted project name (underscores, upper case) instead of raising an error. The project may already have been submitted and the index may not allow renaming the package (although PyPI allows it through a support ticket).

SIP based packages are not installable from PyPI and the SIP team hasn’t fixed this. Writing a setuptools package for SIP is non-trivial. This means we must use their build process (configure, make, make install). Eggs and wheels don’t allow installing files in system directories. SIP based packages stick close enough to non-system directories in a venv. We could make a setup.py with zip_safe=False and put all files installed by make install in package_data, then use bdist_wheel on it to create a binary platform-dependent wheel. This is a bit more error-prone (e.g. a .so file appearing in an unexpected place would break things) without much benefit as these wheels probably can’t be shared across machines. In order to support SIP based packages, we install them without pip and reuse the dev venv in pre-commits as to not incur the performance hit of waiting for a SIP package to compile.

pytest-testmon is not compatible with pytest-xdist, –maxfail, –ff, –lf and –cov to name a few. It sometimes misses changes that do cause test failures. For these reasons, we default to using xdist instead of testmon. We may revisit testmon once it supports xdist. You can still install and use –testmon yourself, you probably shouldn’t add –testmon to setup.cfg though as that would allow for commits with failing tests.

It is guaranteed that any release commit can be checked out and by installing requirements.txt, all tests will succeed. We cannot guarantee this for commits with editable requirements. We could require one to first ensure the editable requirement’s repo is clean, and the commit has been pushed. We could then pin onto that particular commit. But this is too restrictive; you would no longer be able to amend or rebase commits in editable requirements as you need to push it as soon as you use it in another repo you are working on.

No effort is made to handle packages which fail to mention all of their dependencies, instead those packages should be fixed upstream. Should such a situation occur and the package maintainer refuses to fix it, a work around could be made: a list of packages, ct-mkvenv would install these in list-order with the version specs specified in requirements.txt, then ct-mkvenv would do another pip install -r requirements.txt for the other packages (without needing to exclude the misbehaving packages from requirements.txt).