Opened 9 years ago
Closed 9 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 by , 9 years ago
| Has patch: | set |
|---|---|
| Triage Stage: | Unreviewed → Accepted |
| Type: | Uncategorized → Cleanup/optimization |
comment:2 by , 9 years ago
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!
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).