The Security Team tries very hard to avoid causing behavior changes in patch releases, but sometimes we have to. As the number of issues handled under the security process continues to increase[1], “sometimes” multiplied by a larger number equals “will come up more often”.
This information is easy to miss if it only exists spread across several patch release notes. Changes in documented behavior can be documented with the feature, as we did for August’s two GeoDjango issues, but that’s not collected in any central place. Otherwise, undocumented features only get mentioned in the X.Y release notes under “Minor incompatible changes in X.Y”, and we aren’t in the habit of updating that after X.Y ships.
So (purely hypothetically ) imagine a breaking change in next month’s Django 6.1.2 release that only affects undocumented functionality. Should we:
repeat this information nowhere else but the patch release note?
include it in the 6.1 release notes, under “Minor incompatible changes in 6.1”
same, but in a separate “Minor incompatible changes since 6.1” heading
same, but move that separate heading to the 6.2 release notes?
I have a slight preference for 2, simply flattening the fact whether something shipped in Django 6.1 or 6.1.2. (I sort of presume that if that difference is material, it’s likely to involve documented functionality, in which case we will continue to have a versionchanged:: 5.2.20 in the docs for that feature, and from there, it’s not too difficult to lookup which other patch releases hit on the same day.)
Thoughts?
The exploding quantity is forcing the CVE program to clarify that you can’t just slap a single CVE on a single patch release fixing multiple issues. ↩︎
To be clear, I mean documenting these changes in docs/releases/6.2.txt, which contains the release notes currently under development on main. When a security fix with backward incompatible implications is applied to the released branches, each resulting patch release receives its own note. The change also lands in main, but main has no corresponding patch release; unless it is mentioned in 6.2.txt, the next feature release is the only release containing the change that receives no release-note entry of its own for the potentially breaking change.
A section in 6.2.txt, perhaps titled “Behavior changes introduced in recent patch releases”, would make clear that these changes were introduced earlier and are not new in 6.2, while still making them visible to people consulting the next feature-release notes.
This also covers users who upgrade to 6.2 from a patch release that predates one of these changes. Even users who installed the relevant patch may not have read every intervening patch-release note. Each entry could identify the exact patch releases in which the change first appeared (optional).
Oh, do you mean someone upgrading from a pre-fix 5.2.x release directly to the latest 6.1.x and reading only 6.1.txt?
I was thinking of someone upgrading from a pre-fix 5.2.x, 6.0.x, or 6.1.x release to 6.2 and reading only 6.2.txt.
So, to cover both cases, I guess we should add the note to the development release notes on main, also update the latest released feature version’s notes under a separate “Changes introduced in X.Y.x patch releases” section, and backport that documentation update to its stable branch?
That’s it exactly. I feel we could avoid that duplication by choosing either option 2 or 3, since anyone updating directly to 6.2 is already “on the hook” for reading the “minor breaking changes” in every release in between?
That makes sense. I see one remaining gap, though: someone may have read 6.1.txt when 6.1.0 was released, remained on an early 6.1.x version that predates the change, and later upgraded directly to 6.2. They would naturally read 6.2.txt, but would have no reason to reread 6.1.txt and discover information added after they originally read it.
More generally, although users skipping feature releases are technically “on the hook” for reading all the intervening release notes, I’m not sure it is realistic to expect everyone upgrading from 5.2 to 6.2 to read the 6.0 and 6.1 notes as well—particularly given the common misconception that an LTS-to-LTS upgrade is inherently a safe direct jump.
That is why I still see value in a brief summary in 6.2.txt.
I’m on board with a brief summary of 6.1.x breaking changes in 6.2 (following release). What if that brief summary was basically just a link to the relevant section of the 6.1 notes? So option 3 plus an obvious link right at the top of the “Backwards incompatible changes in 6.2” section?
Option 3 would have been my vote — assuming a change is needed. (It’d help people updating after the initial release, who might not check out the patch releases. Folks who already updated but don’t check the patch notes aren’t likely to recheck the main release notes either, but I’m not sure how much sympathy they need.) Otherwise Option 1, which I read as “Carry on as we are”. Q: Has a need for a change been shown?
I guess I’m not convinced there is a problem here. If users don’t read patch release notes, they may also not read release notes at all or any separate compatibility page.
If someone misses this information and encounters a breakage, I think they would search for it (or use AI to search for it). We already have the patch release notes and the release blog post.
Before maintaining another source of information, I think we should wait for evidence from users that the existing release notes and blog posts are insufficient. We can then address the specific discoverability problem they are encountering.
I read feature release notes, but I’ve never reviewed the patch release notes when upgrading a feature version. I may have read them at some point when they came out (unlikely), but reading them skeptically in the context of upgrading a certain project is different.
I don’t know if “size” is the right word for it, but my thought experiment stipulated undocumented behavior, which is definitional for SemVer (SemVer makes no sense without an API boundary). We’re going “above and beyond” to advise about changes outside the API boundary.
That does not match my experience working on production Django projects. Patch releases are commonly treated as routine maintenance, with the expectation (perhaps sometimes incorrectly) that they should not require special preparation. Feature-version upgrades, by contrast, are deliberate pieces of work: teams review the feature release notes, assess backwards-incompatible changes, and test their projects accordingly.
Therefore, I don’t think that skipping patch release notes implies that those users will also skip feature release notes. That difference in how the two kinds of upgrades are approached is precisely why I think restating patch-introduced behavior changes for the feature-release audience would be useful.
A new option would be to make the patch release notes stand out more.
We could update the heading from “Django 6.0.8 release notes” to “Django 6.0.8 release notes - contains backwards incompatible changes”
These would be easy to spot when looking at the release index page: Release notes | Django documentation | Django
Since I have come back to this a few times today, I would want to know:
Is it really a security issue if it’s in internal / not publicly exposed code?
How internal is it?
Are there any consequences to only fixing it in the next major/minor release?
If I were just voting without comment, I would pick (I’m not a fan of Django breaking things on patch releases.)
If it were 100% unavoidable, I would lean toward Sarah’s suggestion to make it very publicly known in the release notes heading.
I only read release notes for major and minor versions unless someone tells me I need to pay attention. I think Dependabot throws so many 100s/1000s of updates at us a year; I’m not even sure how anyone can keep up.
#1
Assume the breakage is a rare side effect of the security fix, not the main point. Say during review, we find that switching from Flawed Algorithm to Safer Algorithm causes some error case to raise TypeError instead of ValueError. We never guaranteed what exception would be raised, but we want to be nice and tell people their except ValueError will break. Assume there’s no way to re-raise the TypeError because it’s upstream in python and we’d have to run Flawed Algorithm again to distinguish it.
#2
A different example would be CVE-2026-15307: we had a feature designed for convenience that is almost impossible to handle correctly by a reusable app like the admin. But that breaks someone who says “hey, I liked this convenient way to process my trusted data–I knew it was safe!”
Re:
Are there any consequences to only fixing it in the next major/minor release?
What was unfortunate about #2 is – yes. It was easily the highest severity issue out of any I’ve seen so far since being a fellow.
That could be a useful additional addition, I’m +1, but I don’t think it’s sufficient: it does not address the main discoverability problem I’m concerned about. Projects generally get patch upgrades through PyPI and their dependency files, not by browsing the release docs index. Feature release announcements also tend to link directly to that version’s notes, bypassing the index again.
If users never read the patch release notes, changing their title will not reach them. It could complement, but not replace, surfacing the information in the feature-release upgrade path.
There will be a feature release once a year but patch releases almost every month.
Skipping a patch release (going from 2028.3 to 2028.5) is more common. It’s possible every 2 months.
In this case, the proposed solutions don’t help. There is no reason why someone successfully running a feature version would think to consult the feature version release notes after a patch upgrade.
Our backwards incompatible changes in a patch is a last resort and should impact very few users.
Out of that limited user group, we need them to skip a patch. Out of that more limited group, they need to happen to be doing the annual upgrade for the proposals to help them.
I would want to see our users comming forward and saying that our backwards incompatible changes in a patch impacted them and they missed the release notes. Then we can learn where they expected to see this information.
) imagine a breaking change in next month’s Django 6.1.2 release that only affects undocumented functionality. Should we:
(I’m not a fan of Django breaking things on patch releases.)