Brightspot Gradle Plugin Upgrade Guide

Follow the documentation found in the Brightspot Gradle Plugins guide.

After upgrading Gradle, you will need to upgrade your GHA Java version to 11 (this is separate from the version which the project is running on).

Upgrading GHA version

If your GHA was upgraded via the MTM program, follow the examples here to change your Java version to 11: GitHub - perfectsense/brightspot-github-actions-workflows.

Upgrading project Java 11

Check if project is on cloud

The easiest way to determine if your project is on cloud is if there is an existing etc/containers/Dockerfile in the project.

If this is the case, your project is likely configured to run on a cloud environment.

In this scenario, follow the below link to upgrade the project to Java 11 on cloud:

After following the core guide, please follow these additional steps to complete the Gradle upgrade.

Follow-up on TCT:

If TCT was changed from error to warning during the initial verification of TCT, you will need to make sure this is updated.

In each front end bundle’s build.gradle, add this only if you have set TCT to warning in a previous step.

bundle {
 testMode = 'warn'
}

Verify use of root Styleguide templates

Some projects might be using templates in the root Styleguide. This can cause issues of views not loading on the front end if additional steps are not taken to handle these cases.

How to verify

To verify, there are a few code audit steps to take.
What you should check:

1. Is there markup in root Styleguide templates?
2. Any css/js in root Styleguide?
3. Are there usages of ServletViewTemplateLoader in the project?
4. Are there usages of ViewRenderer with a null template loader?

Resolution

If these are encountered, we can modify our {site/web}/build.gradle similar to the below commit:

import brightspot.gradle.viewgen.RootStyleguideConfigPlugin

plugins {
	...
    id 'com.brightspot.root-styleguide
}

war {
	...
    // root styleguide needs to be in the WAR file because various view rendering uses ServletViewTemplateLoader which
    // works only with templates from the root styleguide
    from configurations.named(RootStyleguideConfigPlugin.ROOT_STYLEGUIDE_CONFIGURATION_NAME)
}

Updates to migration/build.gradle

The first step here is to evaluate whether this code is still necessary to have in the project. Migration dependencies often pull in older code, which can fail and slow down development. As such, please confirm with your team if the code is still in use or not.

If not in use:

• Comment out all relevant lines referencing migration within settings.gradle and */build.gradle.

If in use:

• Convert usages of api → implementation.
• Add plugins to the top of migration/build.gradle:

plugins {
    id 'com.brightspot.java-core'
}

• Add implementation enforcedPlatform ("com.psddev:migration-bom:5.2.21.1") into dependencies of migration/build.gradle.
• Add shared unit tests to the dependencies:

dependencies {
    sharedTest 'com.brightspot.shared-tests:pack-standard-backend-unit-tests'
}

1. Push your work and ensure GitHub builds it successfully.
2. Ensure Gradle cache credentials are set in the GitHub secrets and that Gradle build cache is functioning properly by running ./gradlew -DdisableLocalCache clean build after the project has built in GitHub. You should see output that several tasks were from cache, and the build should complete quickly.

Checkstyle errors after Gradle version upgrade

The gradle upgrade also brings a checkstyle upgrade which differs in how it validates java file import groups. Specifically, the standard CustomImportOrder checkstyle module will validate that all import groups do not contain any blank lines inside each group. If these errors appear after the gradle upgrade, add suppression directives as follows.

Resolution:

In etc/checkstyle/checkstyle.xml, add the following just inside the <module name="Checker"> element:

<module name="SuppressionFilter">
    <property name="file" value="${config_loc}/suppressions.xml"/>
    <property name="optional" value="false"/>
</module>

Add a config/checkstyle/suppressions.xml file with the following content:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE suppressions PUBLIC
        "-//Checkstyle//DTD SuppressionFilter Configuration 1.2//EN"
        "https://checkstyle.org/dtds/suppressions_1_3.dtd">

<suppressions>
    <suppress message="Extra separation in import group before" />
    <suppress message="Separación extra en el grupo de importación antes" />
</suppressions>

ModificationFieldInternalNamePrefixTest errors

These might occur after performing the upgrade. While it makes sense to fix these errors, doing so would result in a data-breaking change.

Resolution:

To solve this build issue, add a list of files that are to be excluded from the test (only include the files that caused it to fail, not all/other files).

Documentation on this can be found here: https://perfectsense.github.io/delivery-notes/modules/shared-tests.html#ignoring-certain-classes-for-dynamic-tests

After adding these exclusions, the rule will remain active for new code, but will not be active on the listed files.

Example:

core/src/test/resources/brightspot/objecttype/ModificationFieldInternalNamePrefixTest.ignored.txt

brightspot.core.action.actionbar.ActionBarSettings
brightspot.core.ad.AdsFrontEndSettingsModification
brightspot.core.listmodule.DateRangeQueryModifier
brightspot.core.page.TypeSpecificFrontEndSettingsModification
brightspot.core.page.TypeSpecificPageElementsModification
brightspot.core.page.opengraph.image.OpenGraphImageSettingsModification
brightspot.core.seo.SeoSettingsModification
brightspot.core.timed.TimedContentData
brightspot.facebook.FacebookSettingsModification
brightspot.form.field.captcha.CaptchaSiteSettings
brightspot.form.field.required.RequireableData
brightspot.google.dfp.GoogleDfpFrontEndSettingsModification

Could not resolve dependency {strictly version}

This could be encountered after upgrading your Gradle plugin.

This error means that your project could not determine the forced version for a specific dependency since there were varying forced dependencies within different BOMs.

Example error:

Execution failed for task ':{project}-migration:enhanceMainClasses'.
> Could not resolve all files for configuration ':{project}-migration:runtimeClasspath'.
   > Could not resolve com.google.api-client:google-api-client:{strictly 1.31.1}.
   
   ...

The error should alert you to the differing versions in this case.

For example, your error might have three different sections:

> Could not resolve com.google.api-client:google-api-client:{strictly 1.31.1}.
     Required by:
         project :{project}-migration

...

   > Could not resolve com.google.api-client:google-api-client:1.31.1.
     Required by:
         project :{project}-migration > com.psddev:brightspot-dependencies:4.5.15.12
         project :{project}-migration > com.psddev:google-youtube:4.5.142-x6b6acf

...

   > Could not resolve com.google.api-client:google-api-client:1.30.9.
     Required by:
         project :{project}-migration > com.brightspot.go:go-dependencies:0.17.2
         project :{project}-migration > com.google.apis:google-api-services-youtube:v3-rev20200526-1.30.9

Resolution:

This is telling us a few things:

• Our project is strictly 1.31.1.
• brightspot-dependencies and google-youtube are forcing 1.31.1.
• go-dependencies and google-api-services-youtube are forcing 1.30.9.

From this, we can see all of the BOMs which are enforcing that dependency.

Step 1: Verify strictness on a project level

First, verify that your project isn’t forcing 1.31.1 manually, and that the strict version on your project is implicit from other dependencies. You can do this by looking in the build.gradle files for that dependency and force = true. If your project is forcing the dependency, take note of which version it is forcing and remove the force = true.

Step 2: Verify the other BOMs which are forcing the dependency

Step 3: Find the highest forced version

Now that it is known which versions are forced where, select the highest of these, and use that as the version to force in the solution.

Step 4: Update settings.gradle

Next, open your settings.gradle file and add the highest version in the error message as a substitution.

Our highest version is 1.31.1, so that is the one we will substitute.

dependencyConstraints = [
    ...,
    'com.google.api-client:google-api-client': 'com.google.api-client:google-api-client:1.31.1', // Brightspot 4.5.15.12 conflicts with Go 0.17.2
]

After doing this, the project will no longer have ambiguity in which version should be forced and the project should build successfully.

RichTextElementPreviewTest Failure

After upgrading Gradle, you may encounter this error.

It will indicate an absence of the implementation of the writePreviewHtml method if preview=true in the RichTextElement annotation.

Example error:

Failed to map supported failure 'org.opentest4j.AssertionFailedError: brightspot.rte.blockquote.BlockQuoteRichTextElement has @RichTextElement.Tag(preview = true) but writePreviewHtml() is not overridden' with mapper 'org.gradle.api.internal.tasks.testing.failure.mappers.OpenTestAssertionFailedMapper@76500501': null 
RichTextElementPreviewTest > testForRichTextElementPreviews() > brightspot.rte.blockquote.BlockQuoteRichTextElement FAILED
org.opentest4j.AssertionFailedError at RichTextElementPreviewTest.java:32

Resolution:

Implement writePreviewHtml on any affected rich text elements. There is no need to populate the method.

@Override
public void writePreviewHtml(ToolPageContext page) throws IOException {
    // do nothing - we want `preview = true` to have this display full-width in the CMS but otherwise
    // there's no need for previewing anything
}

DuplicateClassFileTest Failure

After completing the Gradle plugin upgrade, you may encounter DuplicateClassFileTest error. This issue arises because during the Gradle upgrade process you are asked to remove the root build.gradle file, which may cause some file exclusions to be inadvertently removed.

Example error:

DuplicateClassFileTest > testForDuplicateClassFiles() STANDARD_ERROR     Nov 14, 2023 3:14:50 PM brightspot.general.DuplicateClassFileTest testForDuplicateClassFiles

Here is an example of the exclusion that could have been removed:

exclude group: 'com.brightspot.go', module: 'lib-model-l10n-core'

Resolution:

Add back the root build.gradle file, and add back the exclusions.

allprojects {
    configurations.all {
        // We've materialized lib-model-l10n-core so prevent it from being included by all projects
        exclude group: 'com.brightspot.go', module: 'lib-model-l10n-core'
    }
}