On 12/06/2014 07:24 PM, Andrew Godwin wrote: > My notes from the meeting say "experimental API language", so I may have > taken an adjective too literally when I made this. > > Nevertheless, the key thing _I_ want to see is for us to commit to > putting release notes out for some of Django's APIs that aren't > necessarily considered stable. The 1.7 database API stuff was the main > catalyst for this; those are changes and APIs we should have documented, > and fall somewhere above "internal" (as we expect people to build > third-party database backends), but not tie ourselves into a 3-release > deprecation cycle for. > > How about we change the label from "Experimental" to something like > "Unstable", but keep the same provisions - documentation called out as > "unstable feature", separate section in the release notes, etc. That > establishes a clear level between "internal and we don't care about it" > and "stable and publicly documented". The alternative is to change the > DEP to just say we're going to start putting release notes up for > certain internal APIs, and then somehow list the ones we will somewhere > (probably on the API stability page).
Something doesn't feel quite right to me about the word "unstable" either. I guess it's technically applicable to something we want to retain the freedom to change, but it seems pejorative. I guess I would favor your latter alternative: don't introduce new terminology, just document some things (probably starting with the database backend interface) in the internals/ section of the docs, and clarify that while APIs documented there are not covered by the back-compat policy, changes to them will be noted in the release notes. I don't really think there's a problem with the word "internal" here: from the perspective of the vast majority of Django users, the database backend API is internal, but there are a few (maintainers of third-party backends) for whom its a very important interface, so we document it. Carl -- You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group. To unsubscribe from this group and stop receiving emails from it, send an email to django-developers+unsubscr...@googlegroups.com. To post to this group, send email to django-developers@googlegroups.com. Visit this group at http://groups.google.com/group/django-developers. To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/5483D5BA.3060800%40oddbird.net. For more options, visit https://groups.google.com/d/optout.
signature.asc
Description: OpenPGP digital signature
