Document how the Python version is determined and more

Code improvement description

The documentation for how a pip-Dependabot actually checks for new and compatible versions and which files are actually modified is very poor/nonexistent. It requires trial and error to figure out what works.

What Python version does it use?

This question is so simple, I feel silly for asking it. But I found no mention of this anywhere in the official documentation. The closest I found was this random blog post and even there it does not say, which Python version it uses.

Example setup:

I have a Python package that is supposed to work on multiple different Python versions, e.g. >=3.9, <4.0. I use pip-compile with different Python versions to generate my pinned dependency files as you are supposed to do and end up with 3.9-requirements.txt, ... and 3.12-requirements.txt. The 3.9 file contains the following line:

backports-strenum==1.2.8

The and 3.12 file does not because backports-strenum is only compatible with Python <3.11. Let's say I allow dependency-type: 'all' in my dependabot.yaml. What will Dependabot do, when it reads that line?

A) Just blindly check for a new version of that specific package, find that 1.3.1 exists and propose that bump?
B) Use a Python version >=3.11, see that the package is not compatible and propose removing it?
C) Just ignore it completely?
D) Throw an error?

I don't know, Regis... I think I might need to ask the audience for this one.

Click here for the answer!

The answer is **C)**. It does not change that line. Why? Don't know.

My point is not even that Dependabot should do one thing over another. My point is that this should be documented.

I sifted through the logs it produced in the Github Actions and found that it said somewhere it uses Python 3.12. That's nice, but it would have been nicer, if I could know this beforehand by reading the documentation.

Does it actually run `pip-compile`?

Or does it just check any *requirements.txt file it finds against the most recent packages compatible with its Python version (apparently 3.12 right now)?

I have a pyproject.toml file like this:

[build-system]
requires = ["setuptools", "setuptools-scm"]
build-backend = "setuptools.build_meta"

[project]
name = "dependabot-tests"
requires-python = ">=3.9, <4.0"
version = "0.0.1"
dynamic = ["dependencies"]

[tool.setuptools.dynamic]
dependencies = { file = "requirements.in" }

And my requirements.in file defines the direct dependencies.

Again, as in my example above, I generate different *requirements.txt files from the same requirements.in via pip-compile.

Dependabot apparently just modifies the *.txt files. Or does it read the *.in file? Or does it actually run pip-compile against the pyproject.toml? If so, why did it not overwrite/remove that line with the incompatible sub-dependency from the 3.9 file?

Is this documented somewhere? Unfortunately not and unfortunately I am not a ruby developer. There are a few issues here that seem vaguely related, such as #1455, where the last comment is just wild. Or #8365, which does not explain a lot.

In general, a sufficiently complex tool like pip-compile, which is supposedly supported by just doing package-ecosystem: 'pip', has so many ways of operating that there is no way for people to know, how exactly Dependabot handles it. Maybe the developers that implemented this feature think their way of using pip-compile is obvious, but it is not to me.

Again, this is not a bug report. A bug report would mean that the software behaved in a way that contradicts the documentation. Since the behavior is not documented, I can't say, if what I experience is a bug or the software working as intended. Please improve the documentation.

dependabot / dependabot-core