[i18n-discuss] ICU 4.0.1 [PSARC/2009/129 FastTrack timeout 03/02/2009]

[Nicolas Williams]

I looked at what the user guide has to say about compatibility and it
looks like we could even safely go with Committed for the C and Java
interfaces.

For C++ the claim is that "C++ binary compatibility is not supported is
primarily because the design of C++ language and runtime environments
present extreme technical difficulties to doing so. Stable C++ APIs are
source compatible, but applications using them must be recompiled when
moving between ICU releases."

Select quotes and links below.

I strongly recommend Uncomitted for the Java and C interfaces, and
Volatile for the C++ interfaces.

Nico


 - http://icu-project.org/userguide/design.html#Version_Numbers

  "For ICU releases and the library (code) versions, a change in the
   minor version number indicates releases that may have feature
   additions or may break binary compatibility, such as between version
   2.0 and 2.2. A change only in milli (or micro) version numbers
   indicates a maintenance release that is binary compatible. For
   example, ICU 2.6.2 was a maintenance release which was binary
   compatible with ICU 2.6 and ICU 2.6.1. (See below for more
   information on ICU Binary Compatibility .)

   ICU reference releases are denoted by even minor version numbers
   (like ICU 1.6 or 3.4). Previously, odd minor version numbers (like
   ICU 1.7) were used for “enhancement” releases. Currently, odd numbers
   are used only for unreleased unstable snapshot versions."

 - The policy on source compatibility is described here:
 
   http://icu-project.org/userguide/design.html#ICU_API_compatibility

   And it looks quite compatible with ICU being Uncommitted in Solaris.
   
 - http://icu-project.org/userguide/design.html#ICU_Binary_Compatibility

  "ICU4C may be configured for use as a system library in an environment
   where applications that are built with one version of ICU must
   continue to run without change with later versions of the ICU shared
   library.

   Here are the requirements for enabling binary compatibility for ICU4C:

    1.  Applications must use only APIs that are marked as stable.
    2.  Applications must use only plain C APIs, never C++.
    3.  ICU must be built with function renaming disabled.
    4.  Applications must be built using an ICU that was configured for
        binary compatibility.
    5.  Use ICU version 3.0 or later.
   
   Stable APIs Only.   APIs in the ICU library that are tagged as being
   stable will be maintained in future versions of the library. Stable
   functions will continue to exist with the same signature and the same
   meaning, allowing applications to continue to work without change.

   Stable APIs do not guarantee that the results from every function
   will always be completely identical between ICU versions . Bugs may
   be fixed. The Unicode character data may change with new versions of
   the Unicode standard. Locale data may be updated or changed, yielding
   different results for operations like formatting or collation.
   Applications that require exact bit-for-bit, bug-for-bug
   compatibility of ICU results should not rely on ICU
   release-to-release binary compatibility, but should instead link
   against a specific version of ICU.

   To verify that an application uses only stable APIs, build it with
   the C preprocessor symbols U_HIDE_DRAFT_API and U_HIDE_DEPRECATED_API
   defined. This will produce build errors if any draft, deprecated or
   obsolete APIs are used.

   C APIs only. Only plain C APIs remain compatible across ICU releases.
   The reason C++ binary compatibility is not supported is primarily
   because the design of C++ language and runtime environments present
   extreme technical difficulties to doing so. Stable C++ APIs are
   source compatible, but applications using them must be recompiled
   when moving between ICU releases.

   Function renaming disabled. Function renaming is an ICU feature that
   allows an application to explicitly link against a specific version
   of the ICU library, and to continue to use that version even when
   other ICU versions exist in the runtime environment. This is the
   exact opposite of release-to-release binary compatibility – instead
   of being able to transparently change ICU versions, an application is
   explicitly tied to one specific version.

   Function renaming is enabled by default, and must be disabled at ICU
   build time to enable release to release binary compatibility. To
   disable renaming, use the configure option

         configure -–disable-renaming [other configure options]

	 (Configure options may also be passed to the runConfigureICU
	 script.)

   To enable release-to-release binary compatibility, ICU must be built
   with --disable-renaming, and applications must be built using the
   headers and libraries that resulted from the –-disable-renaming ICU
   build

   ICU Version 3.0 or Later. Binary compatibility of ICU releases is
   supported beginning with ICU version 3.0. Older versions of ICU (2.8
   and earlier) do not provide for binary compatibility between
   versions.
   "

 - There's also a data compatibility section:

   http://icu-project.org/userguide/design.html#ICU_Data_Compatibility