Re: clarification of API backwards-compatibility policy

2013-02-20 Thread Jannis Leidel 
On Tue, Feb 19, 2013 at 10:56 PM, Carl Meyer  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

Jannis

-- 
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 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?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.

Re: clarification of API backwards-compatibility policy

2013-02-19 Thread Russell Keith-Magee 
On Wed, Feb 20, 2013 at 5:56 AM, Carl Meyer  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 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?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.

Re: clarification of API backwards-compatibility policy

2013-02-19 Thread Aymeric Augustin 
On 19 févr. 2013, at 22:56, Carl Meyer  wrote:
> 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/

I said that on IRC recently, was called out, and then filed a ticket:
https://code.djangoproject.com/ticket/19728

> 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.


I agree, the docs don't reflect the current practice and should be changed.
We aren't using the underscore convention (at least, not consistently).
Even if we wanted to, that ship has sailed.

-- 
Aymeric.



-- 
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 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?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.

Re: clarification of API backwards-compatibility policy

2013-02-19 Thread Alex Gaynor 
I agree, backwards compatibility for an API should be opt-in (via
documenting), not opt-out (via naming).

Alex


On Tue, Feb 19, 2013 at 1:56 PM, Carl Meyer  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?
>
> Carl
>
> --
> 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 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?hl=en
> .
> For more options, visit https://groups.google.com/groups/opt_out.
>
>
>


-- 
"I disapprove of what you say, but I will defend to the death your right to
say it." -- Evelyn Beatrice Hall (summarizing Voltaire)
"The people's good is the highest law." -- Cicero

-- 
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 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?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.

clarification of API backwards-compatibility policy

2013-02-19 Thread Carl Meyer 
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?

Carl

-- 
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 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?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.