Hi Andrew, Thanks for putting together this proposal.
On 12/05/2014 09:32 PM, Andrew Godwin wrote: > One of the results of discussions at Django Under The Hood was support > for the idea of marking APIs "experimental" - that is, document them and > include them in mainline Django releases, but away from the standard > Django deprecation cycle while still not hiding them under the > "Internal" moniker (these would be APIs for public consumption). I must have missed this discussion at DutH (or my memory is just poor). I recall discussion of better documenting changes to the database backends API for the benefit of third-party database backends, but I don't recall discussion of a new "experimental" designation. > Of particular interest here is the issues we faced with some of the > migration APIs during the 1.7 release; 1.7 might have been able to > release faster if we could have released early with some parts of > migrations and the schema editor marked as "experimental" and iterated > on it during the main release cycle, and communicated with third-party > database backends more effectively and given them documentation and > release notes. > > There's an extra consideration here if we should extend the proposed > part of the release notes listing experimental changes to also include > internal changes, and possibly a separate discussion to be had about > marking some of the Django database API as stable (or experimental for a > release or two, then upgrade them). > > The pull request for the DEP is here: https://github.com/django/deps/pull/10 As the DEP notes, our backwards-compatibility policy already includes a longstanding carve-out for anything documented within the "internals" section of the docs. We haven't made much use of this for documenting actual internal APIs (most of that section of the docs is about contribution process), but we could. What does an "experimental" designation gain us that the "internals" section doesn't? (I am hesitant about the term "experimental" -- it implies both that we don't trust the code in question, and that the code is likely to "graduate" to fully-backwards-compatible status in the near future. I'm not sure that those two things will be true in every case of an internal API that we may want to document.) 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 [email protected]. To post to this group, send email to [email protected]. 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/5482C6C3.7030801%40oddbird.net. For more options, visit https://groups.google.com/d/optout.
signature.asc
Description: OpenPGP digital signature
