#23252 closed Cleanup/optimization (fixed)
Better communication of features that will no longer be available in a release
| Reported by: | 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 , 10 years ago
| Severity: | Normal → Release blocker |
|---|---|
| Summary: | StrAndUnicode removal missing from 1.7 relnotes/deprecation plan → Better communication of features that will no longer be available in a release |
| Triage Stage: | Unreviewed → Accepted |
| Type: | Uncategorized → Cleanup/optimization |
comment:2 by , 10 years ago
| Owner: | changed from to |
|---|---|
| Status: | new → assigned |
comment:3 by , 10 years ago
| Resolution: | → fixed |
|---|---|
| Status: | assigned → closed |
comment:5 by , 10 years ago
I don't think we should commit to documenting the removal of private, undocumented APIs.
Version 0, edited 10 years ago by (next)
comment:6 by , 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.
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:
"
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.