Opened 4 years ago

Closed 4 years ago

#25485 closed Cleanup/optimization (fixed)

Deprecation notice on GenericRelation is confusing

Reported by: Joey Wilhelm Owned by: nobody
Component: Documentation Version: 1.8
Severity: Normal Keywords:
Cc: moldy Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

In looking up the documentation for GenericRelation, I ran across the deprecation notice which looks like:

class GenericRelation
Deprecated since version 1.7:
This class used to be defined in django.contrib.contenttypes.generic. Support for importing from this old location will be removed in Django 1.9.

This was initially confusing to me for two reasons. To alleviate repetition, here's the related conversation from IRC:

< TheJoey> Is it just me, or is this deprecation notice a bit confusing? https://docs.djangoproject.com/en/1.8/ref/contrib/contenttypes/#reverse-generic-relations
< moldy> TheJoey: not to me
< TheJoey> moldy: It makes it sound to me, at first, like GenericRelation itself is deprecated. And then it goes on to say that the old location will be removed, but not where the new location is.
< moldy> TheJoey: i do wish that the reference docs would say "class the.import.path.Object" in these headings (the <dt>), but that's a more general issue
< giarc> TheJoey a little... it'd be nice to have the current import location mentioned
< TheJoey> moldy: Or at least showing more import statements in the example code
< TheJoey> Problem is, just looking at this doc, I have no idea where to pluck GenericRelation from. Except that I just read something earlier today about that particular deprecation, so I already have an idea where to look.

Perhaps this could be stated more along the lines of "This class definition was moved from django.contrib.contenttypes.generic to django.contrib.contenttypes.fields", or the example below could actually show the import.

Change History (3)

comment:1 Changed 4 years ago by Tim Graham

Has patch: set
Triage Stage: UnreviewedAccepted
Type: UncategorizedCleanup/optimization

PR -- does it help? I'm reluctant to backport to 1.7 since this causes problems for the translated versions of the docs (there isn't a way to update the translations for non-stable versions of the docs).

comment:2 Changed 4 years ago by Joey Wilhelm

Looks good to me, except your new line 529 says "this old location" vs all the others saying "the old location". Other than that, it looks much better. Thank you!

comment:3 Changed 4 years ago by Tim Graham <timograham@…>

Resolution: fixed
Status: newclosed

In f79682ea:

[1.8.x] Fixed #25485 -- Improved deprecation docs for contenttypes reorganization.

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