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

[Cornelius Schumacher]

On Tuesday 05 May 2009 12:05:46 Thiago Macieira wrote:
>
> 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.

This is a good policy.

One remark: When changing namespaces, symbol names, include paths etc. it 
would be good, if it would be done in a way that ends with a sane name, once 
the lib is included in stable kdelibs, so starting with a libfooexperimental 
is better than ending with libfoonowreallystablewemeanit.

-- 
Cornelius Schumacher <schumacher at kde.org>