Refinement to pre-commit in CI

[benjaoming]

We have hardcoded the main branch in our pre-commit CI check:

readthedocs.org/tox.ini

Lines 76 to 78 in c8f9b85

	# FIXME: use `github.event.pull_request.base.sha` in `--from-ref` because if
	# the base branch is different, this won't work as expected
	pre-commit run --from-ref main --to-ref HEAD

A way to get around this is to create a specially named branch pre-commit-base in the following step:

https://github.com/readthedocs/readthedocs.org/pull/9793/files#diff-78a8a19706dbd2a4425dd72bdab0502ed7a2cef16365ab7030a5a0588927bf47R45

I'm thinking that a replacement using Circle CI parameters would work:

      - run: git branch -f --track pre-commit-base << pipeline.git.base_revision >>  # needed for comparisson in pre-commit

pipeline.git.base_revision

The long (40-character) git SHA of the build prior to the one being built. Note: While in most cases pipeline.git.base_revision will be the SHA of the pipeline that ran before your currently running pipeline, there are some caveats. When the build is the first build for a branch, the variable will not be present. In addition, if the build was triggered via the API, the variable will not be present.

[humitos]

A way to get around this is to create a specially named branch pre-commit-base in the following step:

Do we have to create a special branch? Can we just use the pipeline.git.base_revision you found in the command directly?

pre-commit run --from-ref <<pipeline.git.base_revision>> --to-ref HEAD

[benjaoming]

@humitos yes, agreed. When I wrote this, I thought there was a reason to run this from Tox. But there isn't. We can just install pre-commit alongside Tox and run it straight in the Circle CI env.

One layer less 👍

[humitos]

I was saying to keep it running on tox but using that variable.

It's on tox because all the other checks are performed by tox and also because it's useful to run it locally.

[benjaoming]

<<pipeline.git.base_revision>> a variable in the Circle CI yaml, so we have to find a way to pass it to Tox.

Edit: Adding a branch or tagging the revision can probably work fine.

[benjaoming]

We should add here that it's not enough to ensure that we are comparing just the correct base branch, we should also compare to the correct upstream repo. Otherwise an outdated main on a forked repo will lead to unwanted extra linting.