Opened 10 years ago

Closed 10 years ago

Last modified 10 years 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: Andrew Godwin
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 by Russell Keith-Magee, 10 years ago

Severity: NormalRelease blocker
Summary: StrAndUnicode removal missing from 1.7 relnotes/deprecation planBetter communication of features that will no longer be available in a release
Triage Stage: UnreviewedAccepted
Type: UncategorizedCleanup/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 by Andrew Godwin, 10 years ago

Owner: changed from nobody to Andrew Godwin
Status: newassigned

comment:3 by Andrew Godwin <andrew@…>, 10 years ago

Resolution: fixed
Status: assignedclosed

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 by Andrew Godwin <andrew@…>, 10 years ago

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 by Aymeric Augustin, 10 years ago

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 10 years ago by Aymeric Augustin (previous) (diff)

comment:6 by Andrew Godwin, 10 years ago

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