commit 4b860f02dc93e392db347c94aadf79f46c7ad631
Author: Michael Simacek <msimacek(a)redhat.com>
Date: Tue Apr 7 18:13:32 2015 +0200
[doc] Compat versions
doc/jar_file_id_compat.txt | 71 +++++++++++++++++++++++++++++++++++++++++++-
1 files changed, 70 insertions(+), 1 deletions(-)
---
diff --git a/doc/jar_file_id_compat.txt b/doc/jar_file_id_compat.txt
index c226307..cd20759 100644
--- a/doc/jar_file_id_compat.txt
+++ b/doc/jar_file_id_compat.txt
@@ -1,5 +1,74 @@
Handling of compatibility packages, versioned jars etc.
WORK IN PROGRESS
-mizdebsk, 31 Oct 2013
+msimacek, 2015-04-02
+In Fedora we prefer to always have only the latest version of a given
+project. Unfortunately, this is not always possible as some projects
+change too much and it would be too hard to port dependent packages to
+the current version. It's not possible to just update the package and
+keep the old version around as the names, file paths and dependency
+provides would clash. The recommended practice is to update the current
+package to the new version and create new package representing the old
+version (called compat package). The compat package needs to have the
+version number (usually only the major number, unless further
+distinction is necessary) appended to the name, thus effectivelly having
+different name from RPM's point of view. Such compat package needs to
+perform some additional steps to ensure that it can be installed and
+used along the non-compat one.
+
+[NOTE]
+======
+You should always evaluate whether creating a compat package is really
+necessary. Porting dependent projects to new versions of dependencies
+may be a compicated task, but your effort would be appreciated and it's
+likely that the patch will be accepted upstream at some point in time.
+If the upstream is already inactive and the package is not required by
+anything, you should also consider retiring it.
+======
+
+===== Maven Compat Versions
+XMvn supports marking particular artifact as compat, performing the
+necessary steps to avoid clashes with the non-compat version. An
+artifact can be marked as compat by `%mvn_compat_version`. It accepts an
+artifact argument which will determine which artifact will be compat.
+The format for specifying artifact coordinates is the same as with
+<<mvn_alias,`%mvn_alias`>>. In the common case you will want to mark all
+artifacts as compat. You can specify multiple compat versions at a time.
+
+.Dependency resolution of compat artifacts
+When XMvn performs dependency resolution for a dependency artifact in
+a project, it checks the dependency version and compares it against all
+versions of the artifact installed in the buildroot. If none of the
+compat artifacts matches it will resolve the artifact to the non-compat
+one. This has a few implications:
+
+- The versions are compared for exact match. The compat package should
+ provide all applicable versions that are present in packages that
+ are supposed to be used with this version.
+- The dependent packages need to have correct BuildRequires on the
+ compat package as the virtual provides is also different (see below).
+
+.File names and virtual provides
+In order to prevent file name clashes, compat artifacts have the first
+specified compat version appended to the filename. Virtual provides for
+compat artifacts also contain the version as the last part of the
+coordinates. There are multiple provides for each specified compat
+version. Non-compat artifact don't have any version in the virtual
+provides.
+
+.Example invocation of `%mvn_compat_version`
+[source,shell]
+--------------
+# Assuming the package has name bar and version 3
+# Sets the compat version of foo:bar artifact to 3
+%mvn_compat_version foo:bar 3
+# The installed artifact file (assuming it's jar and there were no
+# %mvn_file calls) will be at %{_javadir}/bar/bar-3.jar
+# The generated provides for foo:bar will be
+# mvn(foo:bar:3) = 3
+# mvn(foo:bar:pom:3) = 3
+
+# Sets the compat versions of all artifacts in the build to 3 and 3.2
+%mvn_compat_version : 3 3.2
+--------------
Show replies by date