Webservice as a Stable API

[Gervase Markham]

Max Kanat-Alexander wrote:
> 	We can avoid the entire problem of removing arguments by *always* using
> named parameters when there is more than one argument. Named parameters
> are much easier all around, anyhow.

As Myk says, this sounds like a good idea to me.

> 	For example: we return a hash with 'foo', 'bar', and 'baz'. We cannot
> ever stop returning any of those items. If 'foo' is an integer, it must
> stay an integer for all of eternity. However, we could add a 'qux' item
> later, because that doesn't break old code.

On the same principle, should we make all return values hashes? Or is
that overkill?

> 	3) Functions don't disappear.

But if we end up with a big backwards-compatibility problem, we can
always add doFoo2().

> 	This does mean that if we mark anything as stable, it should only be
> after careful review and testing. In my latest patch against the
> webservice code, I've defined both STABLE and EXPERIMENTAL as ways of
> describing functions, where EXPERIMENTAL means "we think it's stable but
> we're still testing it out". 

I would hope everything is EXPERIMENTAL at the moment!

> Anything labeled "EXPERIMENTAL" should
> become "STABLE" by a final release.

I don't agree (reasonably strongly). This effectively makes all
interface stabilisation block the release. I think it's entirely fine to
ship final releases with things still labelled EXPERIMENTAL. That just
tells people not to use them if they want to be sure their code won't
break. We should not rush stabilisation of an interface.

Gerv