On Sun, Dec 7, 2014 at 6:35 PM, Shai Berger <[email protected]> wrote:
> I like the general idea of experimental API, although Carl and Aymeric's > notes > are important: If we do this, we need to very picky in its use, or else it > just becomes an easy route to avoid committment. In particular, there > should > be a hard-and-fast rule that nothing should be made an "experimental API" > if > it can just be done outside of core. > > For the example given -- backend API -- I think that, again, Carl and > Aymeric > are right; the examples I have more in mind for this are user-facing ORM > features like the expressions, or custom lookups. I think it might be > better > to let people play with them more, in a released version, before setting > the > APIs in concrete. > > With that in mind, I would also reconsider adding a silent warning when the > features are used -- because, if they are for general use (as opposed to > the > use of, say, 3rd-party backend developers) then there's a significant > use-case > where the person who would use the API is not the person who configures the > warnings on the CI. > To my mind, the role of this new status is closer to "provisional", rather than "experimental". It's a recognition of the fact that no matter how many times we ask for pre-release testing, the first *real* test of any API is when it sees real-world use. In some respects, it a return to the pre-1.0 status of Django APIs, where we would endeavour to maintain backwards compatibility if at all possible, but we would be willing to break an API if it was in the best interests of future use. As an example of the sorts of things that got changed see: https://code.djangoproject.com/wiki/BackwardsIncompatibleChanges The difference here is that we're doing it for a specific API or new feature, not for the entire API. I agree that "experimental" status shouldn't be used as a way to avoid commitment. IMHO, the "rules of use" are something like this: * It can only be used for major feature APIs. If a feature doesn't warrant a significant mention in the release notes, then it's either an internal API, or a minor feature that we can live with being locked down. * There is a strict timeline - if a feature is provisional/experimental in vX, then it should automatically be final in vX+1, unless enough changes are made to the API that warrant another provisional/experimental version cycle. However, at each release, the intention should be to lock down all provisional APIs in the previous release if at all possible. * The corollary of this last point is that the release *before* a stable release can't have any experimental/provisional features. * Even though we have the escape hatch, we only use if if we have to. A rapid-deprecation backwards compatible path is preferable to a fundamental backwards incompatible change. For my money, the role of this policy change isn't to introduce instability into Django's process. The role is to give us permission to introduce features which we might not otherwise land (or might delay in landing) due to fears over whether the public-facing API is suitable for use. Russ %-) -- 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/CAJxq84_-%3DvOwbX0jrJrXPCaa7Gr6CW12_5TZ_yvAe%2B2XD_%3Dyyw%40mail.gmail.com. For more options, visit https://groups.google.com/d/optout.
