Opened 11 months ago

Closed 11 months ago

Last modified 11 months ago

#23252 closed Cleanup/optimization (fixed)

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

Reported by: nick.phillips@… Owned by: andrewgodwin
Component: Documentation Version: 1.7-rc-2
Severity: Release blocker Keywords:
Cc: Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

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.

Change History (6)

comment:1 Changed 11 months ago by russellm

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Severity changed from Normal to Release blocker
  • Summary changed from StrAndUnicode removal missing from 1.7 relnotes/deprecation plan to Better communication of features that will no longer be available in a release
  • Triage Stage changed from Unreviewed to Accepted
  • Type changed from Uncategorized to Cleanup/optimization

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.

comment:2 Changed 11 months ago by andrewgodwin

  • Owner changed from nobody to andrewgodwin
  • Status changed from new to assigned

comment:3 Changed 11 months ago by Andrew Godwin <andrew@…>

  • Resolution set to fixed
  • Status changed from assigned to closed

In 173d989c91361243d0638f1e39db7148bc0ea4f8:

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

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

comment:4 Changed 11 months ago by 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.

comment:5 Changed 11 months ago by aaugustin

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.

Last edited 11 months ago by aaugustin (previous) (diff)

comment:6 Changed 11 months ago by andrewgodwin

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

Note: See TracTickets for help on using tickets.
Back to Top