Update API stability doc
|Reported by:||Aymeric Augustin||Owned by:||nobody|
|Has patch:||yes||Needs documentation:||no|
|Needs tests:||no||Patch needs improvement:||no|
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.
- 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.