How-To Upgrade Guidance

The following describes the process and strategy to update your Broadleaf Microservices Release Train version as well the pattern to override a specific library version defined in the Release Train.

How do I update the Release Train version?

Manifest Based Dynamic Project Structure

When using Initializr, the parent POM, broadleaf-microservices-flex-parent, now contains a lot of the "definition" that was previously expected to be defined in the old MS Demo project structure. The version of the flex-parent pom will contain a reference to the appropriate Release Train version. Therefore, to upgrade the Release Train, you should increment the parent version in your manifest and run mvn flex:generate.

# ...
project:
  groupId: com.example.microservices
  packageName: com.example.microservices
  starterParentVersion: [insert RT version e.g. 2.0.0-GA]
  # ...

Alternatively, you can update the version in each of your flex-packages' POMs, the manifest module, and the data-loader module directly:

<parent>
    <groupId>com.broadleafcommerce.microservices</groupId>
    <artifactId>broadleaf-microservices-flex-parent</artifactId>
    <version>[insert RT version e.g. 2.0.0-GA]</version>
    <relativePath/>
</parent>

Legacy Static Project Structure

Generally for the 1.7.x and 1.8.x release train projects, you will want to update the following versions in your root pom.xml to the applicable versions:

<!-- Microservice Versions -->
<properties>
  <blc.release.train>[insert RT version e.g. 1.8.0-GA]</blc.release.train>
  <blc.jpa.core>[insert RT compatible version e.g. 1.7.11-GA]</blc.jpa.core>
</properties>

Note

this allows you to pull in the appropriate Release Train BOM with the harmonized dependency versions. Depending on the level of upgrade, there may be additional code, project structure, or SQL level changes that are applicable as well. Please see the appropriate Release Notes sections for more details.

How do I override Base Dependencies version?

Third-party library security vulnerabilities are addressed as part of Base Dependency releases. These releases are generally able to be plugged into an installation via maven configuration without upgrading the rest of the codebase. In such cases, Base Dependencies may be released separately from Release Train and require upgrading separately. This guide explains that process.

How do I override a specific library or dependency version?

There may be some cases, where you may need to override a specific version of a library or dependency rather than the entire Release Train or Base Dependencies such as for a patch to single service between Release Trains. This may be either an explicit Broadleaf library dependency or a Third Party Library that Broadleaf depends on.

Manifest Based Dynamic Project Structure

In a manifest-based project, you will need to add a <dependencyManagement> section in the POM of each flex-package and potentially the data-loader module depending on the usage of the dependency being updated. In <dependencyManagement> you will need to list the dependency and its version to override it. This section should come before <dependencies>.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.broadleafcommerce.microservices</groupId>
            <artifactId>my-service-to-override</artifactId>
            <version>2.X.X-GA</version>
        </dependency>
    </dependencies>
</dependencyManagement>

Legacy Static Project Structure

In a static project based on MS Demo, you will notice that the root pom.xml of your project defines a dependencyManagement section importing the Release Train BOM. In order to override a specific dependency, you must specify the exact dependency PRIOR to the release train import (order is important).

<dependencyManagement>
    <dependencies>
        <!-- ↓ Any explicit override should appear first BEFORE the release train ↓ -->
        <dependency>
            <groupId>com.broadleafcommerce.microservices</groupId>
            <artifactId>my-service-to-override</artifactId>
            <version>1.X.X-GA</version>
        </dependency>
        <dependency>
            <groupId>com.broadleafcommerce.microservices</groupId>
            <artifactId>broadleaf-microservices-release-train</artifactId>
            <version>${blc.release.train}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Note	This follows the same Spring Boot conventions for projects that don’t inherit a Parent POM. More details around this pattern can be found here

How do I upgrade frontend library dependencies?

Authenticating with Broadleaf’s NPM Registry

Broadleaf produces several Node frontend libraries that are published to Broadleaf’s private NPM registry. Therefore, first you will need to make sure you are logged in using NPM providing your credentials:

npm login --registry=https://repository.broadleafcommerce.com/repository/npm-private/

This will modify your ~/.npmrc file with a token used for authenticating with the registry. Second, you will need to add the @broadleaf scope:

npm config set @broadleaf:registry https://repository.broadleafcommerce.com/repository/npm-private/

Upgrading Libraries

After authenticating, you can add or update dependencies in your frontend project, e.g., AdminStarter or Commerce Next.js Starter, using the following command format to get the latest release for a certain major-minor combination:

# generically
yarn add @broadleaf/<module-name>@latest-<version> --exact
# e.g., this will give the latest 1.10.x patch of Admin components
yarn add @broadleaf/admin-components@latest-1.10 --exact
# e.g., this will give the latest 1.6.x patch of Commerce browse
yarn add @broadleaf/commerce-browse@latest-1.6 --exact

Or you can supply a specific version explicitly:

# generically
yarn add @broadleaf/<module-name>@<version> --exact
# e.g., this will give the 1.10.8 version of Admin components
yarn add @broadleaf/admin-components@1.10.8 --exact

These commands will update your package.json and yarn.lock.

Important

You should rarely modify the versions of dependencies directly in package.json and never modify yarn.lock directly.

Tip	Not every module has changes for each release, so `@broadleaf/admin-components` might increment its version but `@broadleaf/admin-style` and `@broadleaf/admin-tailwindcss` might not change.