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

Matt Ebb matt at mke3.net
Sun Jul 17 13:04:14 CEST 2011


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


More information about the Bf-committers mailing list