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

Sun Jul 17 15:53:46 CEST 2011

+1 to campbell, and keeping fallbacks and deprecation warnings for
some time should really make this easy to manage and evolve

Daniel Salazar
3Developer.com


On Sun, Jul 17, 2011 at 7:49 AM, Campbell Barton <ideasman42 at gmail.com> wrote:
> 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
> _______________________________________________
> Bf-committers mailing list
> Bf-committers at blender.org
> http://lists.blender.org/mailman/listinfo/bf-committers
>