Re: platform compatibility policy

[Maciej Stachowiak <mjs eazel com>]

Havoc, would you like to take ownership of leading discussion, writing
up new drafts that capture the discussion

Havoc Pennington <hp redhat com> writes:

> A useful definition:
>  Major version: 1.0, 2.0
>  Minor version: 1.0, 1.2, 1.4
>  Micro version: 1.2.5, 1.2.6
> 
> So we are defining our versioning scheme implicitly to match changes
> in the devel platform. Major versions break bin/source compat.

I'm not sure we want to lock that into the policy. Everntually, let's
say around GNOME 3 or GNOME 4 platform, we may well decide we never
want to break backwards compatibility again. But on the other hand we
don't want GNOME 4.27 10 years later. But I think it's OK to include
this for now and change the release versioning part of the policy
later, when/if it becomes an issue.

> Maciej Stachowiak <mjs eazel com> writes: 
> > GNOME Platform Compatibility Policy (draft 1)
> > 
> > 1) Within major versions of the GNOME Platform, source and binary
> >    compatibility will be maintained. Release coordinators shall reject
> >    packages provided for a release if they break compatibility.
> > 
> > 2) There are, however, a few exceptions:
> > 
> >    * Security issues that cannot be fixed without an API or ABI change
> >      (although all due consideration should be given to adding new
> >      APIs and deprecating the old ones, when possible).
> > 
> >    * Major bugs (e.g. crashing) which cannot possibly be worked around
> >      by apps
> 
> Not clear to me that this is right; if you break bin compat, then all
> apps start segfaulting. So breaking bin compat is not necessarily a
> sensible solution to a crash bug.

I meant that the soname should be updated as well, so you'd have to
upgrade the apps. Again, the intent here is only a really prominent
crasher where you can't even do a workaround without breaking binary
compatibility. I don't really think this will come up either, so maybe
we should leave making judgement calls like this up to the board.

> Not that I can think of any example of either of these cases in any
> lib ever, so it's probably academic. ;-)
> 
> Perhaps add: if bin compat is broken, the soname must be changed
> appropriately. Then apps will fail to start up instead of weirdly
> segfaulting.

Er, yes, I considered adding the soname thing, I thought that went
without saying and was a technical issue that did not belong in a
policy document but we should probably put it in.

> > 
> >    * Vote of the GNOME Foundation Board of Directors
> > 
> > 3) The Foundation Board shall declare what releases constitute a new
> >    GNOME Platform version; at that time, source and binary
> >    compatibility may be broken. [ note - GNOME 2.0 is currently
> >    planned to constitute a new platform version ]
> > 
> 
> Addressing Alan's point about forward/back compat:
> 
> 4) Adding interfaces to micro version releases should be done only
>    with a very strong justification, and such interfaces should be as
>    small as possible, maybe one or two functions. Large interfaces
>    require at least a minor version revision.
> 
> Rationale (not necessarily part of the policy, though maybe 
> you want to append it):

Rationales should be included in the policy when appropriate.

>  - bugfix micro releases do not get remotely as much QA 
>    or peer review as minor releases
>  - we have had bad experiences in the past; e.g. GnomeDruid 
>    was added and was totally broken
>  - it's hard to document and keep track of which version has
>    what if you add interfaces in micro versions
>  - it makes CVS branches much more annoying to maintain
> 
> "Strong justification" means the changes should be essential hooks for
> some important feature. i.e. just an aesthetic change like adding an
> accessor function or fixing a function name would not be good
> enough. "Large interface" means a whole new facility, such as a new
> widget.

The problem with this section is that it requires a lot of judgement,
unlike the stated standards for when you may break backwards
compatibility. People are going to argue over what is strong
justification and what is a new feature, I think, and my goal for
having a policy is to be able to resolve disagreements just by
pointing to the policy.

 - Maciej