Opened 12 years ago

Closed 12 years ago

Last modified 12 years ago

#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)

19728.diff (4.0 KB ) - added by Tim Graham 12 years ago.

Download all attachments as: .zip

Change History (6)

by Tim Graham, 12 years ago

Attachment: 19728.diff added

comment:1 by Tim Graham, 12 years ago

Has patch: set
Triage Stage: UnreviewedAccepted

I'm not sure if the backwards compatibility note about contrib apps is still valid either?

comment:2 by Carl Meyer, 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 Tim Graham <timograham@…>, 12 years ago

Resolution: fixed
Status: newclosed

In 132d5822b0651bd0f192388693cb22263e68ddf5:

Fixed #19728 - Updated API stability doc to reflect current meaning of "stable".

comment:4 by Tim Graham <timograham@…>, 12 years ago

In 23ef6e1baf29d0390d5b94de0441e19f722d3aab:

[1.5.X] Fixed #19728 - Updated API stability doc to reflect current meaning of "stable".

Backport of 132d5822b0 from master

comment:5 by Tim Graham <timograham@…>, 12 years ago

In db1e8bdc33a8bfa4b47a765cb2a7a66aafa52bad:

[1.4.x] Fixed #19728 - Updated API stability doc to reflect current meaning of "stable".

Backport of 132d5822b0 from master.

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