RFC v3: adding a temporary, non-BC gauranteed, 'private' library (was RFC v2)

[Thiago Macieira]

Em Terça-feira 05 Maio 2009, às 10:49:38, Thiago Macieira escreveu:
> Em Terça-feira 05 Maio 2009, às 09:10:24, Kevin Ottens escreveu:
> > On Tuesday 5 May 2009 09:03:51 Kevin Ottens wrote:
> > > I honestly far prefer a trunk/KDE/kdelibs-experimental over
> > > trunk/extragear/libs.
> >
> > Oh, and to make it clear, I even prefer kdelibs/experimental to both
> > other solutions even if it puts some more work on the packagers
> > initially.
>
> No, it's not. It has to be OUTSIDE kdelibs.

Uh... sorry for the harsh email. I misread your email anyways. (Of course I 
can't tell you what your opinion is or isn't :->)

Anyways, after another heated discussion on IRC we reached a different 
compromise.

Here's the idea:
- we create kdelibs/experimental in trunk/KDE
  yes, it's a subdir of kdelibs
- however, when packaging, the KDE release team will have to split it up:
	kdelibs-4.x.y.tar.gz
	kdelibs-experimental-4.x.y.tar.gz
  the latter contains *only* the experimental subdir; the former contains 
  everything else, except the experimental dir
 - recommendation: add -DKDELIBS_NO_EXPERIMENTAL to kdelibs to check if 
  building without the experimental bits works
 - constraints:
	* kdelibs-experimental-4.x.y.tar.gz MUST build alone (outside of kdelibs)
	* kdelibs MUST NOT depend on anything in the experimental subdir
	  in other words, these two requirements are meant to put 
	  kdelibs/experimental at the same build phase as extragear/libs currently is
 	* public libraries MUST NOT use the experimental in their public API
	* public libraries (outside kdelibs) and any plugins SHOULD NOT use the 
	  experimental API at all (see below)
	* all the current constraints applying to these libraries

In order to break binary compatibility, once per minor release, remember to:
 * change the library soname, to allow installing in parallel
 * preferably, change the include path too
 * preferably, change all exported symbol names (like changing the namespace)
   Changing symbol names is recommended to allow public libraries and plugins 
   to load more than one version into memory without causing symbol clashes
 * changing non-exported symbol names is a good idea (remember that not all 
   targets support visibility=hidden)

For each and every binary compatibility breakage:
 * change ALL applications using this, or at least all in the KDE servers
   (for practical purposes, that means you must restrict the use of this API 
    to a subset that you can reasonably work on)

Binary compatibility breaks can only happen in minor releases. They cannot 
happen in patch-level releases.

When finalising the API and merging into an existing KDE library, you MUST 
change the symbol names (change the namespace or drop it if your target 
library uses none [that is, kdecore or kdeui]). That's to allow applications 
using the previous API to run with the new library without being recompiled. 

If you're not merging into an existing library, then it's just another binary 
compatibility break, albeit the last one.

To all parties involved: is this acceptable? Especially note the release team, 
due to this requiring their work.

PS: this can be applied to phonon-experimental too. It should be released as a 
separate tarball, just like kdelibs-experimental. For now, it's just private 
API and any application using it outside of the phonon tarball is doing so at 
its own risk of breakage.
-- 
Thiago Macieira - thiago (AT) macieira.info - thiago (AT) kde.org
  Senior Product Manager - Nokia, Qt Software
      PGP/GPG: 0x6EF45358; fingerprint:
      E067 918B B660 DBD1 105C  966C 33F5 F005 6EF4 5358
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part.
Url : http://mail.kde.org/pipermail/release-team/attachments/20090505/a00bf83e/attachment.sig