Iterative API design (Was: Re: Matrix as a replacement for Telepathy)

[Sébastien Wilmet <swilmet gnome org>]

On Fri, Aug 25, 2017 at 10:21:07AM -0500, Gary Kramlich wrote:
> > Release 3.0? :)
>
> I know, need more hours in the day :-/  I'll spend some time this
> putting together a 3.0 checklist, but it's not going to be pretty..
>
> > Seriously, all that nice GObjectification cleanup does make it a nicer
> > proposal as a GNOME framework.
>
> Yeah, unfortunately it's incomplete, and if we release now, we're just
> going to have a super long 4.0 cycle too.  I'd rather get through 3.0
> get the GObject based API stable and complete and then get into a
> normal development cycle of feature releases again.

To avoid being stuck for years with non-optimal APIs, what I do in Tepl
is to release a new major parallel-installable version every 6 months if
needed (and up until now it *was* needed, but it's a recent library).

For more details, see the section "Iterative API design and stability
guarantees" at:
https://developer.gnome.org/tepl/unstable/intro.html

Maybe Linux distro packagers don't really like that, but I think what is
more important is that in a few years the library is still relevant,
with good APIs. If the GObjectification takes several cycles, no
problem, the API doesn't need to be perfect all the time, it should be
an iterative process, with frequent releases (e.g. every 6 months), to
apply the agile methodology.

For porting applications to the new versions of the library, I think
it's even easier with more frequent API breaks, because if there is a
huge list of API breaks all at once, it's more difficult to port an
application (a huge commit is necassary just to be able to compile the
code again without errors). Basically, if it hurts, do it more often (if
it is necessary):
https://martinfowler.com/bliki/FrequencyReducesDifficulty.html

--
Sébastien