Resolve Unsupported Dependencies Guide

In some specific cases, code libraries intended to be modified may be present as dependencies. In these cases, the library may have changed in an incompatible way, and there is no direct path to upgrade that library, as it has evolved over time. These dependencies are now considered unsupported and need to be resolved through materialization to avoid build errors after upgrading BOM dependency versions.

First, check whether the unsupported dependencies are even required. In many cases, such dependencies may have been included in starter kits but never used. If the dependency is unused, simply remove it.

If an unsupported dependency is in use, materialize it at the version the project is on before the upgrade. The materialization process will remove the dependency from the build.gradle and replace it with a copy of code from that version in the codebase. The materialized dependency code should continue to function as it has been without further need for modification.

Below is a list of commonly included dependencies that are not supported and should be materialized for continued use.

com.psddev:auth

If this dependency exists on your project, follow the steps below to remediate.

1. Remove the dependency from core/build.gradle.
   
   1. If the project builds after this step, you can treat this as resolved since nothing in the project was using that dependency.
   2. If the project fails the build, continue onto the next step.
2. Run the command ./materialize.sh artifact=auth version={version} skipbuild=true where {version} is the application's Brightspot version prior to upgrading.
3. Note the below guides for com.psddev:auth-social and com.psddev:linkedin, since they directly depend on com.psddev:auth

com.psddev:auth-social

You may run into build errors involving this dependency after materializing com.psddev:auth.

1. ./materialize.sh artifact=auth-social version={version} skipbuild=true where {version} is the application's Brightspot version prior to upgrading.

com.psddev:linkedin

You may run into build errors involving this dependency after materializing com.psddev:auth.

1. Remove the dependency.
2. ./materialize.sh artifact=linkedin version={version} skipbuild=true where {version} is the application's Brightspot version prior to upgrading.

com.psddev:facebook

You may run into build errors involving this dependency after materializing com.psddev:auth.

1. Remove the dependency.
2. ./materialize.sh artifact=facebook version={version} skipbuild=true where {version} is the application's Brightspot version prior to upgrading.

com.psddev:auth-social

You may run into build errors involving this dependency after materializing com.psddev:auth.

1. Remove the dependency.
2. ./materialize.sh artifact=auth-social version={version} skipbuild=true where {version} is the application's Brightspot version prior to upgrading.

com.psddev:atlassian

You may run into build errors involving this dependency after materializing com.psddev:auth.

1. Remove the dependency.
2. ./materialize.sh artifact=atlassian version={version} skipbuild=true where {version} is the application's Brightspot version prior to upgrading.

Removal of express-themes

Verify if the project depends on express-themes-core. This will likely be in the themes build file (possibly pom.xml depending on the age of the project). It could also be in site/build.gradle or core/build.gradle depending on whether you have completed the gradle plugin upgrade.

If this dependency exists, remove the dependency and materialize it instead:

• Run the command: ./materialize.sh artifact=express-themes-core version={version} skipbuild=true, where version is the application's Brightspot version prior to upgrading.

During deployment, you may encounter a compatibility issue between older themes and newer versions. This can result in the absence of certain themes in the deployed environment if the dependency is removed without proper materialization.

com.psddev:native

This dependency is defunct and unused. Remove this dependency.

com.psddev:image

This dependency is defunct and unused. Remove this dependency.

com.psddev:print

Confirm that there are no implementations of any of the 3 abstract classes in this dependency:

• PrintDocument.java
• PrintSlot.java
• PrintSlotValue.java

If there are no implementations of the above classes, this dependency is safe to remove.

If there are classes implementing any of the above classes, run:

1. ./materialize.sh artifact=print version={version} skipbuild=true where {version} is the application's Brightspot version prior to upgrading.

com.psddev.component-lib:cms-user-disable-inline-editing

Remove com.psddev.component-lib:cms-user-disable-inline-editing from any build.gradle files. Functionality in this dependency was moved into the core platform library as of version 4.5.

com.psddev:materialize

Remove com.psddev:materialize from any build.gradle files. Functionality in this dependency was moved into the upgraded Gradle plugin.

The list of dependencies below still exist, but have been moved to alternate locations for stricter release management. Update dependency identifiers as prescribed.

If version management for com.brightspot.go needs to be added to the settings.gradle, ensure that the versions configuration block contains the line in the example below:

    versions {
        ... // likely other versions such as componentLib or brightspot
        brightspotGo = '1.4.5'  // Using com.brightspot.go for library dependencies moved from component-lib
    }

com.psddev.component-lib:cms-redirects

Replace with com.psddev:redirects

com.psddev.component-lib:embargo

Replace with com.brightspot.go:lib-model-embargo

com.psddev.component-lib:query-memoization-util

Replace with com.brightspot.go:lib-util-query-memoization

com.psddev.component-lib:site-simplest-auth

Replace with com.brightspot.go:lib-model-site-simplest-auth

com.psddev.component-lib:util-content-publish

Replace with com.brightspot.go:lib-util-content-publish

com.psddev.component-lib:util-edit-top-html

Replace with com.brightspot.go:lib-util-edit-top-html

com.psddev.component-lib:util-permalink

Replace with com.brightspot.go:lib-util-permalink

com.psddev.component-lib:util-tooluser

Replace with com.brightspot.go:lib-util-tooluser

com.psddev.component-lib:util-unresolved-state

Replace with com.brightspot.go:lib-util-unresolved-state

Materialization is a scripted process for copying the code contents from a dependency at a specified version into the application codebase. In scenarios where dependency libraries are no longer supported by their authors, materialization is a useful process for preserving a snapshot of these libraries for continued future use.

To make use of Brightspot's materialization script, ensure that core/build.gradle contains the com.psddev.component-lib:materialize dependency. Without this dependency, the script will fail with an error.

Most application codebases include a README file with details on materialize.sh, but the important steps can be found below:

1. Navigate to the root of your project.
2. Run ./materialize.sh artifact={artifact} version={version}

It is often useful to add the skipbuild=true flag to the command, since Materialize will otherwise run a build immediately which is not desirable in the middle of the upgrade process.