Use Whitelists in impactBuild scenario

1. Introduction

The purpose of the current implementation of an impact build is to guarantee that all the files impacted by a change within the build scope are identified and added to the build list.

However, there are scenarios, that users would like to have more control over what is built in an impactBuild scenario for a given build configuration without completely losing the impactBuild functionality and move to build lists for example.

Let’s imagine that your Git repository contains a truly monolithic application with thousands of programs and many dependencies. This application is probably composed of several business modules. Developers don’t want to leverage the full impactBuild like it exists in the zAppBuild at the early development phase within a feature branch, because their changes are not completed and rebuilding all impacted files would take a very long time and potentially introduce new issues.

Keep in mind, that it is a good practice to leverage the impactBuild build type to ensure that build is consistent, when the code is integrated into a shared configuration.

2. Limit the scope of an Impact Build

The below solution will document necessary modifications and demonstrate how it is possible to use the --impactBuild along with a whitelist option to control the scope of which files are added to the build list.

The whitelist allows the user to specify which components are in scope for the impact build. Wildcards as well as pathnames can be used to specify the whitelist; eq. it could follow naming conventions, like all the programs starting with eps, or elements from a subdirectory.

2.1. How to configure this solution

2.1.1. modifications to the zAppBuild framework

A new option has to be introduced to the build request called --impactScope. This flag will activate the file filtering based on the whitelist. This new parameter is managed in “method-name” in the build.groovy file.

Copy/Paste this code:

cli.sc(longOpt:'impactScope', 'Flag indicating to build only impacted programs in the scope')

Copy/Paste this code:

if (opts.sc) props.impactScope = 'true'

In the utility script ImpactUtilities.groovy, apply the following changes to validate the identified impacted files against the whitelist, which is provided through an application configuration.

Copy/Paste this code:

// get impactScopeList
List<PathMatcher> impactScopeMatchers = createPathMatcherPattern(props.impactScopeList)

Then modify the logic to select the impacted files.

Copy/Paste this code:

if (props.impactScope) {
	if (matches(impactFile, impactScopeMatchers)) {
		buildSet.add(impactFile)
		if (props.verbose) println "** $impactFile is impacted by changed file $changedFile and on the Impact Scope List. Adding to build list."
	}
	else {
		// impactedFile found but not in the impact scope list.
		if (props.verbose) println "!! $impactFile is impacted by changed file $changedFile, but is not on Impact Scope List. Not added to build list."
	}
}
else {
	buildSet.add(impactFile)
	if (props.verbose) println "** $impactFile is impacted by changed file $changedFile. Adding to build list."
}

2.1.2. impactScopeList property

A new property impactScopeList needs to be provided as an application property in <myApplication/Application-conf/application.properties>.

The property is a comma separated list of pathMatchers, which is used in the contributed logic of the build framework.

Copy/Paste this code:

impactScopeList=**/epsm*.*,**/epscmort.cbl

2.2 Sample invocation

The below test is performed with the sample MortgageApplication. A full build has been made so now it’s possible to use the --impactBuild option to build only the files changed or impacted.

A change is performed on the copybook EPSNBRPM.cpy file, which will impact 4 files.

For simplicity, commands are submitted through the shell in IDz.

2.2.1 impactBuild

DBB collections and metadata are already setup appropriately.

The test is done by running the following command :

$DBB_HOME/bin/groovyz /u/dds0690/userBuildRepo/zAppBuild/build.groovy --sourceDir /u/dds0690/gitlabGil/dbb-zappbuild/samples --workDir /u/dds0690/gitlabGil/work --hlq DDS0690.MORTGAGE --verbose --application MortgageApplication –impactBuild

The build log indicates, that 4 files are added to the build list because of their dependency to the copybook epsnbrvl.cpy.

2.2.2 impactBuild with impactScope option and Whitelist

In the application-conf/application.properties, the list is set up as follows.

Again, a change is performed on the copybook EPSNBRPM.cpy .

The test is done by running the following command :

$DBB_HOME/bin/groovyz /u/dds0690/userBuildRepo/zAppBuild/build.groovy --sourceDir /u/dds0690/gitlabGil/dbb-zappbuild/samples --workDir /u/dds0690/gitlabGil/work --hlq DDS0690.MORTGAGE --verbose --application MortgageApplication --impactBuild --impactScope

The build log indicates, that 3 files were added to the build list, while one file was not. The file epsnbrvl.cbl is not on the whitelist of the impactScopeList build property.

3. Conclusion.

This recipe shows how zAppBuild can be modified to externally control the scope of an --impactBuild and limit it to a subset of an application. It has to be used in the right context of your workflow and the consequence of not having rebuilt all the source files impacted by a change needs to be understood. Also by using the --propsFile option, each developer will be able to manage their own whitelist which is ideally stored in Git.