On Wed, Feb 20, 2013 at 5:56 AM, Carl Meyer <[email protected]> wrote:
> Hi, > > I was just about to tell someone on IRC that Django's > backwards-compatibility policy only applies to documented methods and > attributes (which is how I'd always understood it), but when I actually > went to look at the documented policy it isn't as clear as I'd hoped :/ > > https://docs.djangoproject.com/en/dev/misc/api-stability/ > > That says "All the public APIs – everything documented in the linked > documents below, and all methods that don’t begin with an underscore – > will not be moved or renamed without providing backwards-compatible > aliases." > > This is a bit unclear: does it really mean _every_ method _anywhere_ > that doesn't begin with an underscore? Or does it just mean every > non-underscore method of an otherwise-documented class, even if the > method itself is not documented? > > Either way, I think it would be clearer (and more accurate to actual > practice) if we removed all mention of underscores in this document (or > even explicitly said that we don't generally use the underscore > convention), and clarified that back-compat applies only to documented > modules, classes, methods, and attributes. > > Thoughts? > +1. If I had to try and reverse engineer why the underscore statement was included in the first place, I'd guess it had something to do with _meta, or with some of the more useful (but undocumented) methods on forms. Regardless, I agree that documenting a method should be our mark of API stability, not a naming convention. Yours, Russ Magee %-) -- You received this message because you are subscribed to the Google Groups "Django developers" 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?hl=en. For more options, visit https://groups.google.com/groups/opt_out.
