Wikiadmin: Created page with "== Overview == {{(!)|The intended audience of this document is mainly Openbravo staff. It describes the internal process to be followed whenever a library needs to be upgrade..."

2021-09-14T01:02:00Z

Created page with "== Overview == {{(!)|The intended audience of this document is mainly Openbravo staff. It describes the internal process to be followed whenever a library needs to be upgrade..."

New page

== Overview ==

{{(!)|The intended audience of this document is mainly Openbravo staff. It describes the internal process to be followed whenever a library needs to be upgraded. It applies both to libraries in Openbravo 3 distribution as well as to libraries delivered by modules.}}

From time to time, it is necessary to upgrade a Java library (a jar file) to a newer version. Motivations for this can be diverse:

* Make use of new capabilities
* Get rid of bugs in older version
* Keep updated stack
* ...

To upgrade a library the process described bellow needs to be followed.

== Prerequisites ==

{{(warn!)|If any of the following prerequisites is not satisfied, it will '''not be possible''' to upgrade the library to the newer version!!}}

Note these prerequisites apply also when adding a new library.

=== JDK version compatibility ===

'''All''' jars need to be compatible with, at least, the [http://wiki.openbravo.com/wiki/System_Requirements#Server:_software_stack lowest supported JDK version] by Openbravo. If the jar is compiled with a higher version, it will not be usable in instances running an older one (yes in the other way around).

To check the JDK version used to compile this library:

* Unzip the new jar: <code>unzip ''new-library.jar'' -d /tmp/new-library</code>
* Typically in the <code>META-INF/MANIFEST.MF</code> file there is information about the JDK used to compile it
* It is also posible to check the JDK used to compile <code>.class</code> files. This is done with the <code>javap</code> program checking the major version value. [http://stackoverflow.com/a/1096159/2834815 Here] you can find how they correspond with the currently used numbers. The following script list versions of all <code>.class</code> files, note it can take time in case there are many files in the jar: <code>for f in `find -name "*class"`; do javap -verbose $f | grep "major version"; done | sort | uniq</code>

=== License compatibility ===

Usually libraries select a license and they stick to it among different versions. But sometimes, license is changed from a version to another.

When upgrading a library (or including a new one), you need to check the newer version's license.

* If it is the same as the older version, there is no problem.
* If it is a different one, check in the <code>legal/Licensing.txt</code> file:
** If the new license is already used by any of the included libraries, no problem
** If not, lawyer needs to be asked whether the new license allows to distribute this library

== Process ==

Once the prerequisites are satisfied, the upgrade process consists on the following steps:

=== Check for API changes ===

A new library version can change its public API. To check these changes:

hg clone clone https://code.openbravo.com/erp/devel/api-checks/
cd api-checks/java/tools
java -classpath japitools.jar net.wuffies.japi.Japize as /tmp/old-api apis ''path_to_old_jar'' $JAVA_HOME/jre/lib/rt.jar $JAVA_HOME/jre/lib/jsse.jar +org # change org with the topmost part of the package in the library
java -classpath japitools.jar net.wuffies.japi.Japize as /tmp/new-api apis ''path_to_new_jar'' $JAVA_HOME/jre/lib/rt.jar $JAVA_HOME/jre/lib/jsse.jar +org # change org with the topmost part of the package in the library
./japicompat /tmp/old-api.japi.gz /tmp/new-api.japi.gz | tee /tmp/api-checks.txt

These steps will generate a <code>/tmp/api-checks.txt</code> file detailing all changes that might exist.

==== Check source compatibility ====

Even when the api-checks tools do not find any API changes, there may be source incompatibilities of the new version with the previous ones, see [https://issues.openbravo.com/view.php?id=31432#c81723 here] an example. To check this, review the release notes of the library from the previous to the new version.

==== Check how these changes affect published modules ====

{{(!)|This step is only applicable in case of API changes or when including a new library.}}

Get the code of all published modules in Central Repository. If you have access to Central Repository server, follow next steps, if not, ask someone else (ALO, SHU, AMA...) to do it for you.

git clone https://github.com/alostale/ob-scripts.git
ob-scripts/getAllModules/get-modules.sh
ob-scripts/getAllModules/unzip-modules.sh

This will generate a <code>src</code> directory with sources of all published modules.

Now you can check in the code how the library is used there and whether these changes can affect them. This will give you an idea of the risk of these changes, and might, eventually, require to abort the upgrade process.

===== Adding a new library =====

When adding a new library, check in published modules whether there are already modules that deliver it. Pay special attention whether they include a different version to the one you want to update, because in this case incompatibility issues could appear when installing that module together with your library. Depending on how big the impact is a decision on what to do (proceed and communicate it to owner, abort upgrade...) will be required to be taken.

==== Publish API changes ====

In case there are API change publish them in the [[API_changes|wiki]] following the defined process.

=== Update <code>legal</code> folder ===

All modules containing third party libraries should have a <code>legal</code> directory, which lists the licenses of all included libraries. It also has a <code>Licensing.txt</code> file, listing all library versions and the license they have.

* Update <code>Licensing.txt</code> file to reflect new version
* In case of a different license:
** Include the text if it is not present yet
** Check if old license is still used by any other library, if not, remove the not used license file

=== Update the .classpath file ===

The library is referenced in the .classpath file. If the name of the jar has changed, the file must be updated with the new name.

=== Update wiki ===

When upgrading a library included within Openbravo 3 distribution, update the [[Openbravo_Libraries|wiki page]] that list all the libraries included.

[[Category:HowTo]]

How To Upgrade a Library - Revision history

Wikiadmin: Created page with "== Overview == {{(!)|The intended audience of this document is mainly Openbravo staff. It describes the internal process to be followed whenever a library needs to be upgrade..."