Opened 2 years ago

Closed 2 years ago

Last modified 2 years ago

#19728 closed Cleanup/optimization (fixed)

Update API stability doc

Reported by: aaugustin Owned by: nobody
Component: Documentation Version: master
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 timo 2 years ago.

Download all attachments as: .zip

Change History (6)

Changed 2 years ago by timo

comment:1 Changed 2 years ago by timo

  • Has patch set
  • Triage Stage changed from Unreviewed to Accepted

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

comment:2 Changed 2 years ago by carljm

+1 to this patch. I don't think there should be a special case for contrib apps either. Simple is good.

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

  • Resolution set to fixed
  • Status changed from new to closed

In 132d5822b0651bd0f192388693cb22263e68ddf5:

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

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

In 23ef6e1baf29d0390d5b94de0441e19f722d3aab:

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

Backport of 132d5822b0 from master

comment:5 Changed 2 years ago by Tim Graham <timograham@…>

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