Better communication of features that will no longer be available in a release

[nick.phillips@…]

django.utils.encoding.StrAndUnicode is gone from 1.7 having been deprecated in 1.5, but this is not mentioned in the 1.7 relnotes, nor in the linked deprecation plan. Only place I found it mentioned was as deprecated in 1.5 relnotes.

[Russell Keith-Magee]

This is a valid point that a few people have made in the past. At the core, the issue is that the release notes tell you what was deprecated in *this* release, but doesn't contain any reference to what has reached the end of it's deprecation cycle and will therefore no longer be available.

The information about what has been deprecated is still available - it's just not contained in the document someone is reading when they're upgrading. It isn't necessarily obvious that when you're reading the 1.7 release notes, you may also need to pay attention to the 1.5 release notes (and possibly the 1.6 release notes as well for fast deprecation path) to get the full picture.

This came up in an in-person discussion at PyCon AU; the suggestion made there was a simple line in the 1.7 release notes, at the top of the "deprecated features" section, that said something to the effect of:

"This release completes the deprecation cycle for features deprecated in 1.5 and 1.6:

• Removal of django.contrib.localflavor
• Removal of django.contrib.markup
• Removal of AUTH_PROFILE_MODULE
• Streaming behaviour of HttpResponse
• ...

"
with the bullet points being no more than a heading linking to the relevant section in the 1.5/1.6 release notes, as appropriate.

Yes - this is duplication of information. Yes, this information should have been obvious if you were listening to all the warnings generated when you ran your project under 1.6. But yes, we're all human, and sometimes ignore the big loud warning. It costs us very little to add this minor redundancy in the docs, but the communication gains are large.

Marking as a release blocker because it should be addressed before the 1.7 release notes are finalised.

[Andrew Godwin <andrew@…>]

In 173d989c91361243d0638f1e39db7148bc0ea4f8:

Fixed #23252: Call out removed features in release notes.

Also added StrAndUnicode mixin note to deprecation plan as it was
missing.

[Andrew Godwin <andrew@…>]

In 9cc5d99bdeff5be0f8df1618b989050061ed5629:

[1.7.x] Fixed #23252: Call out removed features in release notes.

Also added StrAndUnicode mixin note to deprecation plan as it was
missing.

[Aymeric Augustin]

I don't think we should commit to documenting the removal of private, undocumented APIs.

EDIT: oops -- that one was documented, sorry. I remember creating deprecation paths for a few private APIs when porting to Python 3, so the existence of a deprecation warning isn't a sufficient reason to add something to the deprecation timeline. But in that case, it should have been there.

[Andrew Godwin]

Yeah, it was in the 1.5 release notes, so I figured it was already documented anyway.