[Bf-committers] Can we please stop breaking APIs?

Sun Jul 17 15:49:34 CEST 2011

Update, added back bgl.Buffer.list, but it prints a deprecation warning.
also added back slice support and fixed a crash on bad index access
(since nobody found this in ~5 years tells me hardly anyone uses
bgl.Buffer but whatever...).

Since 2.5x my stance on blender API has always been to manage,
documented breakages along the way since we evolve more then design,
developers tend to add something that seems like a good idea at the
time and later on discover it didn't work as intended or... later on
add other functionality which makes the original out of place.
We've even had functions in for over a year that never even worked
(crashed infact), and nobody reported it. So I just don't buy it that
once we call it stable that we should improving.

@Erwin,
The difference in blender is an application, not an SDK or a language.

@Matt, you say that it is not documented is not a good reason to
change/remove the feature, interesting that between py 3.2.0 and 3.2.1
they removed __class__ from the global namespace of a class, we used
this in 6 or so places and I certainly noticed when blender broke on
update. I reported a bug but was told I should never have been using
it because its not documented. - Just to say other projects use this
rationale - ofcourse you can argue both ways.

So, everyone can agree that breaking blender is bad.

But what we can't agree on is:
- What is the blender API???
  Operators? Addons? Python Modules?, Addons which have modules with
other scripts might use?, any function in a module (even if its not
defined in __all__ or documented)...
And RNA, do we attributes in RNA that do nothing just so scripts don't break?

If we really be strict about it, we cant remove tool options or
preferences (even if they are not used) because a script could use it.

Ok, this is not so much like changing bgl.Buffer, but it _is_ why I
say our api will never be stable.
However Its also silly to think that because some variable changes
from a boolean to an enum that the api is horrible and scripts wont
work anymore, which is why, practically (IMHO) this is not as bad as
it sounds.

On Sun, Jul 17, 2011 at 11:23 PM, Erwin Coumans <erwin.coumans at gmail.com> wrote:
> A stable and backwards compatible API (and file format) is very important.
>
> Imagine if the C standard kept breaking its backwards compatibility every year?
>
> I think you owe it to your users to keep the API stable backwards compatible until a major version update (2 -> 3 -> 4, that's why Blender 2.5 should be called 3.0).
>
> My 2 cents,
> Erwin
>
> On Jul 17, 2011, at 6:00 AM, Nathaniel Lane <carbon.based.life.form.from.earth at gmail.com> wrote:
>
>> I must say I agree with this completely. While I understand the need to make some occasional changes, on the whole it seems to be bad practice to change it as much as it has been recently.
>>
>> On Jul 17, 2011, at 5:04 AM, Matt Ebb <matt at mke3.net> wrote:
>>
>>> I have a few things to say on this topic...
>>>
>>>
>>> On Sat, Jul 16, 2011 at 8:37 AM, Campbell Barton <ideasman42 at gmail.com>wrote:
>>>
>>>> On Fri, Jul 15, 2011 at 10:35 PM, Diego B <bdiego at gmail.com> wrote:
>>>>>> Nope, the api is not stable and probably wont be until blender
>>>>>> development ceases.
>>>>>
>>>>> so.. that mean that the api never will be stable ? because blender is
>>>>> always in development, like
>>>>> any other software.
>>>>
>>>> In practice we end up stabilizing most areas and don't just break
>>>> stuff indefinitely - But bigger changes mean api breakage is
>>>> unavoidable in most cases - BMesh, Particle Rewrite, Curves/Nurbs
>>>> branch... etc.
>>>>
>>>
>>> I don't think it follows that because blender is always in development (like
>>> any other software) that anything is up for grabs and users can never expect
>>> to be able to rely on a stable API. I think most people can understand that
>>> if a major part of the software changes internally, then the API may have to
>>> change as well, and with a managed path of warning and deprecation, the pain
>>> of transitioning can be managed.
>>>
>>> But this is not the sort of problem that is in question here - some of these
>>> changes, which I thought would stop after the 'stable' 2.5 release, are
>>> smaller, syntactic changes. They're not due to any major internal
>>> reorganisations, they're not part of fixing design problems, they're little
>>> things that really aren't that *necessary*.
>>>
>>> Like the previous change that affected me (which I only found out about when
>>> things stopped working), it was moving ExportHelper from io_utils to
>>> bpy_extras.io_utils. That was something that has nothing to do with
>>> reflecting changes internally in blender, it was a somewhat arbitrary
>>> decision to make things 'nicer' or more organised.
>>>
>>>> From the point of view of a developer who's involved in blender, who reads
>>> every commit log, who hangs out in IRC, who knows exactly what's happening
>>> in the API, this may not seem like a big deal, but for other developers
>>> outside that circle, or users who just want to their tools to work when they
>>> download a new blender, it's a huge difference - it's the difference between
>>> something working or not working at all - there are no varying degrees of
>>> difficulty here.
>>>
>>> Trying to make the api syntactically nice is not a bad goal on its own, but
>>> it *is* a problem when it conflicts with the API's usability. And that
>>> usability is not just about how much you have to type, or if the names are
>>> good syntactically, it's about how much trouble it is to actually develop
>>> tools with it and get work done. Having an unstable API that can change for
>>> seemingly small and arbitrary reasons really damages the API's usability
>>> much more than less-than-beautiful syntax or organisation does.
>>>
>>> So the legitimate need for having things well organised and with nice syntax
>>> and naming has to be balanced with having a usable, stable API. In some
>>> cases (like the one I brought up, IMO) the solution should be to just sigh,
>>> and live with something that's not 100% perfect, because fixing it causes a
>>> greater problem than it solves. In other cases, this can be handled with
>>> deprecation, warnings, grace periods to allow people to transition.
>>>
>>> Agree we should deprecate in some cases - at the moment its arbitrary
>>>> when to do so. Currently I just check if any addons/scripts use it and
>>>> if its documented.
>>>> If not, this is a reasonable indication its not widely used. (nobody
>>>> complained when convert_to_pyobject() was renamed for eg.)
>>>>
>>>
>>> This is absolutely not a reasonably indication. The fact is you really don't
>>> know at all who is using this stuff out there. I've done a reasonable amount
>>> with the 2.5 API now - not extensive by any means, but none of my stuff is
>>> included in addons.
>>>
>>> The benefit of having a python API is that you don't need to spend time
>>> being involved in IRC, mailing lists, etc in order to get work done
>>> developing tools. Scripters and TDs can just write stuff in python and never
>>> show a single other soul, or keep it for their studio to use internally, or
>>> distribute it themselves on the net, or give it to a client who has hired
>>> said coder to make a python tool. The API is not just to enable blender
>>> developers to make included blender tools or addons in python, there's a
>>> much, much wider world outside that sphere. So anything that can improve
>>> interaction and communication that doesn't involve being deeply involved in
>>> blender dev (eg. prior warnings in documentation, deprecation messages,
>>> grace periods, etc) is very much appreciated.
>>>
>>> Anyway, I really appreciate the work that's being done in the API, and it is
>>> miles ahead of what we had before. I just don't want to see baby thrown out
>>> with the bathwater, having a API that can be considered nice at a given
>>> moment in time, but is a total pain to use for real work because it's
>>> constantly breaking.
>>>
>>> cheers
>>>
>>> Matt
>>> _______________________________________________
>>> Bf-committers mailing list
>>> Bf-committers at blender.org
>>> http://lists.blender.org/mailman/listinfo/bf-committers
>> _______________________________________________
>> Bf-committers mailing list
>> Bf-committers at blender.org
>> http://lists.blender.org/mailman/listinfo/bf-committers
> _______________________________________________
> Bf-committers mailing list
> Bf-committers at blender.org
> http://lists.blender.org/mailman/listinfo/bf-committers
>

-- 
- Campbell