[fedora-java] About compat packages

[Mikolaj Izdebski]

Recently there were some discussions about compat packages on IRC.
I wanted to present how I think compat packages should be used.
I hope it will bring some sanity on this matter.


Imagine the following situation.  You are maintainer of a package.
There is a new upstream version, but you know or suspect it may be
incompatible with previous version and update could cause breakage for
some dependants of your package.

The first thing you should do is announce such update in advance.  Try
to be specific in terms of planned update schedule (what is going to
happen at which point of time).  Either send this announcement to some
mailing list (devel or SIG) or to all maintainers of dependant
packages.

After discussing potential problems with interested parties you can
proceed with updating your package.  It's nice to have a consensus,
but that's not always possible.

After you prepared your update you can share it with other
maintainers.  You can use a repo on your fedorapeople.org account, a
side tag in Koji or push it directly to rawhide.  Then maintainers of
dependant packages can test if their packages work with the updated
version of your package and if not then take some action.

Lets look at three different possibilities:

Case 1.  A dependant package works without change with the updated
dependency version.  That's great, it can immediately benefit from
features and bugfixes of new version.  Nothing more to do.

Case 2.  A dependant package needs a simple modification to work with
updated version.  Package maintainer prepares a patch, applies it in
Fedora package and sent it upstream.  Fedora package immediately
starts to benefit from new version of dependency.  Upstream can accept
the patch and benefit too.

Case 3.  A dependant package does not work with new version of your
package and needs some changes to port it.  Package maintainer for
some reason cannot prepare the patch (lack of time, skills etc.).
Fedora package maintainer takes a copy of old version your library and
turns it into a compatibility package.  A comaintainer or other person
reviews it and they add new package to Fedora.  A RFE is sent to
upstream asking to update to new dependency version.  Hopefully in
future upstream will implement the RFE and compatibility package will
be removed from Fedora.

To sum up, procedure of dang:
  1. announce big updates in advance
  2. push the update
  3. fix dependant packages (if needed)
  4. only if absolutely needed, package a compatibility version

The above works in all cases.  If you package newer version as
compatibility package you are only preventing innovation and make
dependant packages using old, obsolete software.


Some (other) best practices:
  0. Introduce compat packages only if absolutely needed.
  1. All compat packages should have older version than default package.
  2. Compat packages should have version suffixes, default package
     should not.
  3. Compat packages should be retired as soon as they are no longer
     needed.
  4. Prefer requires on default package, even if you need to patch
     your package

-- 
Mikolaj Izdebski
IRC: mizdebsk