Fixes #10.

Problem

The pyramid-app cookiecutter already has caching of the .tox directory on GitHub Actions, as do our pre-existing Pyramid apps, and pip-sync updates the venvs from the requirements files each time CI runs. Our Python packages don't currently cache .tox on GitHub Actions (neither the ones using the pypackage cookiecutter in this repo nor the ones using h-cookiecutter-pypackage). This means:

• CI runs for packages take longer because they have to install all the dependencies every time
• When a new version of a dependency gets released that can cause CI for our packages to break on main and on PR branches. This can be really annoying when you come to send a PR for a package and find that CI is broken

Solution

This PR adds caching of the .tox directory for the pypackage cookiecutter. Consequences:

• CI will run faster because all the dependencies don't need to be installed every time. This isn't as big a deal as for our apps because our packages tend to have far fewer dependencies but it's still significant: I think it should save anything from 30s to a few minutes on each CI run.

• CI won't break on main or on pull requests if a new version of a dependency is released that breaks our package because CI won't use the new version of the dependency: it'll use the previously cached version. We've effectively pinned our dependencies on CI but by using cached .tox directories instead of pinned requirements files.

• If the project's test dependencies in the tox.ini file change tox should recreate the venvs from scratch (this is tox's default behaviour) which will install any new test dependencies (and uninstall any that've been removed) and also upgrade all dependencies to their latest versions. So a new version of a dependency could break CI in this case. Note that there's no concept of syncing/updsting a venv in place like pip-sync does, that's not applicable here because we don't have pinned requirements file and it's not needed as much because recreating the venvs of packages (which have far fewer dependencies) from scratch is much quicker than doing so for apps

• If the project's production dependencies in the setup.cfg file change that will cause a cache miss because the hash of setup.cfg is included in the cache key, so the venvs will be recreated from scratch. Again this will install any new dependencies and also update all dependencies to their latest versions so a new version of a dependency could break CI

• When new versions of dependencies are released we actually want CI to upgrade to them because we want to test our packages against new versions of dependencies and get notified if they're broken. For this reason the scheduled nightly CI run of a package always recreates the venvs from scratch. If the nightly run passes then GHA will update the cached .tox dir and future CI runs on main or on a branch will use the new versions of the dependencies. If the nightly run fails then GHA will not update the cache (this is GHA's default behaviour) so non-nightly CI runs on main or on branches won't be broken.

  • Not yet implemented: we will get notified in Slack if the nightly run fails.

• If your branch name ends in -rm-tox-dir then CI on your branch will delete and recreate the venvs. This is necessary when the nightly run is broken by a new version of a dependency and you want to send a PR with a fix. Your PR wouldn't be tested against the new version of the dependency because it'll use the cached version. If you add -rm-tox-dir to the end of your branch name then your PR will be tested against the latest versions of all dependencies. PRs with -rm-tox-dir will not affect the cached .tox directories seen by CI runs on main or other branches: PR branches can only see files cached by workflow runs on their own branch or on main (again: default GHA behaviour).

• When running CI manually via the web interface there's a Delete and recreate cached .tox dir checkbox that you can use to run against the latest versions of all dependencies. If such a workflow run on main succeeds it'll update the cached venvs for future runs on main or other branches. If it fails it won't (default GHA behaviour). Manual workflow runs on non-main branches won't update the cache for main or other branches even if they succeed (default GHA behaviour).

• We'll be able to see in the GitHub Actions logs exactly what versions of all the dependencies were used for each workflow run: tox prints out the output of pip freeze by default (tox-faster disables this locally but not on CI)