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

[Campbell Barton]

On Mon, Jul 18, 2011 at 2:17 AM, Knapp <magick.crow at gmail.com> wrote:
> I think it is clear what is needed.
>
> Devs:
> Devs retaining the freedom and flexibly to continue to innovate and improve
> blender without being boxed in by old stuff, standards and crud.
>  (I am sure without having to document it would be wonderful too! :-)).
>
> Programmers / Users:
> Documentation of changes that are clear and easily available. Perhaps they
> should ship with the product. Perhaps the change of the intro graphic would
> be a signal to watch out for changes?
>
> A transition period for that change to take effect that throws
> deprecation warnings during which old and new should continue to work. No
> one has addressed how long this should be. Should it be 6 months? That would
> make it one Ubuntu cycle. Or maybe 12 months? That should be enough time for
> anyone.

Throughout this discussion deprecation has always been an option and
something we agree can be used at times, my main concern is that we
deprecate stuff and don't remove it as happened with 2.x time frame
for removal - every second release?, whatever it is we need to be able
to manage it but I think a year is too long.

I am not trying to be difficult here, but there are cases it doesn't
really make sense or isn't likely to even help much.

- Operator arguments, which are effectively a part of the api since
for example exporting an object to some file format depends on them,
many scripts use operators, any change to an operator argument could
break a script. Also consider we never really standardized on these,
even now I need to go over all importers and exporters and make their
arguments consistent with eachother.

- API's which are mostly for internal use - eg: `addon_utils.enable()`
may need to have keyword arguments modified, `rna_info` module which
is used for document generation may need to be changed too. I think
its fair to say their are our own internal apis which are not likely
to be used by extensions and we can keep updating these making
breaking changes when needed - because they are written for a very
specific purpose, they are also not apart of our api docs.

- RNA attributes, in this case I think its fair to separate things
like bpy.context.scene.objects from
bpy.context.user_preferences.filepaths.use_save_preview_images, where
accessing some very specific settings, changes in user preferences
IMHO are acceptable without long discussions + deprecation +
documentation, this goes for some other areas of the api which are not
likely to be used by scripts, rna access to logic bricks, some parts
of our windowing api.

- Remove modules which are not used, sometimes we think to add utility
modules which don't end up getting used at all, (even remain
non-function and buggy in a recent instance), in this case its just
not useful to deprecate IMHO.


To allow changes in these areas to me this is pragmatic & common
sense, but it does go against the "don't break the api" mantra.

> It was said that an API is not a language but really for anyone that
> programs in it all day long, it is. Changing it is in effect changing the
> language that the programmer has to work in, often in annoying pointless
> ways (at least to the programmer). I see it like saying printf is not part
> of c language, its just a function, but we all know it is and changing it
> would really piss off a lot of people.

Agree with this for core functionality, 'bpy', 'bpy.props',
'bpy.context', 'mathutuls', 'mathutils.Vector', ''... but further
there are too many details that may change in sub modules.

> Change is good when it is progress and results in a better product. We are
> all willing to put up with that but we don't like changes that do not appear
> to benefit us. I know that sadly we programmers do not know the benefits
> that the changes bring us because they are often hidden but we do know the
> pain of it when they get in our way and slow us down and piss off our bosses
> and customers.

Sure but its subjective, my main concern is that we give an api which
is misleading in its implementation.
With newer developers you see mistakes because if misunderstandings
about how the api works.

I clearly remember being fed-up with the 2.4x api and having to read
its source code more then the api reference because it was just very
confusing as to how the api was meant to work.

While not every change is to this end, heres an example of how
bgl.Buffer.list was confusing.

# this does nothing (creates a list, modifies it and throws it away)
buf.list[0] = 1, 2, 3

# this _does_ do something, since the list is made up of wrapped data
buf.list[0][0], buf.list[0][1], buf.list[0][2] = 1, 2, 3

# So using a function in this case makes it more clear that the return
value doesn't hold a connection to the original data.
# a python developer can see that this function performs a conversion
rather then accessing internal data as is common with attributes.
buf.to_list()[0] = 1, 2, 3

# Now .to_list() is not an equivalent of .list, since I changed it to
convert recursively for multi dimensional buffers
# instead .list should now be replaced with slicing which is more
useful because it can be assigned too.
ls = buf.list

# ...is deprecated for
ls = buf[:]

> Thanks devs for all the good, hard work!
>
> --
> Douglas E Knapp
>
> Creative Commons Film Group, Helping people make open source movies
> with open source software!
> http://douglas.bespin.org/CommonsFilmGroup/phpBB3/index.php
>
> Massage in Gelsenkirchen-Buer:
> http://douglas.bespin.org/tcm/ztab1.htm
> Please link to me and trade links with me!
>
> Open Source Sci-Fi mmoRPG Game project.
> http://sf-journey-creations.wikispot.org/Front_Page
> http://code.google.com/p/perspectiveproject/
> _______________________________________________
> Bf-committers mailing list
> Bf-committers at blender.org
> http://lists.blender.org/mailman/listinfo/bf-committers
>



-- 
- Campbell