I believe we should backport this change to 5.2.x, 5.1.x, and 4.2.x. None of those branches pin docutils beyond requiring a minimum version of 0.19 (and 4.2.x does not even require any minimum). Once Sphinx releases with support for docutils 0.22, test runs on those stable branches will start failing due to incompatibility with the admindocs code using writer_name.

This also affects production usage when projects install dependencies from scratch or update them periodically. Since docutils 0.22 lists support for Python 3.9 and above, it is a valid candidate for Django 4.2.x environments (Python 3.8 is already EoL and thus longer listed as supported).

Hey @carltongibson, @felixxm! Sarah and I would need some input from you as former Fellows about whether there is a established policy or expectation around the following:

A recent docutils release (0.22) broke admindocs due to an API change (see ticket-36535 for details). This PR fixes that issue, and we are now deciding whether to backport it to 5.2.x (only) or also include backports for 5.1.x and 4.2.x.

I'm in favor of backporting because:

• Our documentation in 5.1 and 4.2 explicitly states that we support docutils >= 0.19. That makes 0.22 a valid install candidate for those stable versions.
• Since we don't pin docutils, test environments or production deployments that install from scratch or periodically update will get 0.22. This will break tests and usage of admindocs.
• I think this breaks an implicit promise: we either support the latest version of a dependency (within a supported Python version range), or we pin (from-to) to avoid issues.
• Given the fix is very low risk, I'd rather we backport it to preserve compatibility, rather than enter a broken state or rush to patch stable branches later.

Sarah would be against backporting because:

• Is not clear if Django guarantee support for newly released dependency versions in already-published Django versions.
• There's no history that we can find of backporting compatibility for new third-party releases to old Django branches.
• Docs saying "docutils >= 0.19" wasn't meant to imply open-ended support.
• Pinning docutils in tests' requirements.txt would be sufficient to avoid test failures in CI for stable branches, without requiring new stable releases.
• Historically, older stable branches only receive security and crash-level fixes so this arguably does not qualify.

We'd appreciate your guidance on what's expected here: whether we should treat support for newer versions of dependencies as something we actively maintain across all supported branches, or whether that's out of scope unless there's a pressing reason.

Thanks!

I'd not be so generous (at it's probably against our backport policy) 🤔 . In the past we backported such changes only to releases in the mainstream support (not in extended support) for other releases I'd pin versions. For example ticket-31751:

615e321
3b5e307
fc2a368

Yes, same here. There's no ground for a backport to the extended support branches. Backporting a pin and a docs change would be OK, if we think that has value.

(If I'm still on Django 4.2, say, now I'm going to test and spot a break in a dependency update and pin that myself.)

Thank you both! I've pushed the removal of 4.2.24 and 5.1.12 release notes.

Doc tweaks for 5.1.x: #19694