#19728 closed Cleanup/optimization (fixed)
Update API stability doc
| Reported by: | Aymeric Augustin | Owned by: | nobody |
|---|---|---|---|
| Component: | Documentation | Version: | dev |
| Severity: | Normal | Keywords: | |
| Cc: | Triage Stage: | Accepted | |
| Has patch: | yes | Needs documentation: | no |
| Needs tests: | no | Patch needs improvement: | no |
| Easy pickings: | no | UI/UX: | no |
Description
https://docs.djangoproject.com/en/dev/misc/api-stability/ says that public APIs include:
- everything that's documented
- everything that isn't underscore-prefixed
As far as I can tell, the underscore convention isn't widely used in Django, and in practice we consider that only documented API are public.
Besides:
- the list of stable APIs in the document is most likely out of date.
- special casing django.utils doesn't seem very useful nor user-friendly.
I suggest to update this doc to reflect the current practice. We could simply say: "everything that's documented is stable ie. subject to a deprecation policy for major changes."
I'm opening this ticket after an IRC discussion that also led to thread on django-users.
Attachments (1)
Change History (6)
by , 12 years ago
| Attachment: | 19728.diff added |
|---|
comment:1 by , 12 years ago
| Has patch: | set |
|---|---|
| Triage Stage: | Unreviewed → Accepted |
comment:2 by , 12 years ago
+1 to this patch. I don't think there should be a special case for contrib apps either. Simple is good.
comment:3 by , 12 years ago
| Resolution: | → fixed |
|---|---|
| Status: | new → closed |
Note:
See TracTickets
for help on using tickets.
I'm not sure if the backwards compatibility note about contrib apps is still valid either?