ReasonToBuildDocumentation

Reason To Build Documentation

Overview

The ReasonToBuildDocumentation custom Groovy task analyzes and documents the reason why each file was built during a zBuilder build. It distinguishes between files that were built because they were changed versus files that were built due to dependencies (impacted files). This information is captured in the DBB Build Report as metadata records and can be used for analysis, reporting, and testing decisions.

Contents

Folder/File	Description
groovy/documentReasonToBuild.groovy	Groovy script that implements the logic for analyzing and documenting build reasons.

Installation Instructions

Copy Files

• Clone this DBB Community Repository to your workstation.
• Copy the documentReasonToBuild.groovy script to the $DBB_BUILD/groovy directory.

Note: The Groovy script must reside in the $DBB_BUILD/groovy subdirectory to be automatically discovered by the task configuration.

Integrate with dbb-build.yaml

Add the ReasonToBuildDocumentation task to your dbb-build.yaml configuration. The task should be placed in the impact lifecycle after the Languages task. The Languages task is responsible for populating the BUILD_LIST context variable, which is required by this task to document build reasons.

Example dbb-build.yaml configuration:

lifecycles:
  - lifecycle: impact
    tasks:
      - Start
      - ScannerInit
      - MetadataInit
      - ImpactAnalysis
      - Languages    # Defined in Languages.yaml
      - ReasonToBuildDocumentation  # Document build reasons
      - Finish

tasks:
  - task: ReasonToBuildDocumentation
    script: groovy/documentReasonToBuild.groovy

How It Works

The documentReasonToBuild.groovy script performs the following:

1. Retrieves Build Context: Reads the CHANGED_FILES and BUILD_LIST context variables populated by the ImpactAnalysis task.
2. Categorizes Files:
   • Changed Files: Files that were modified and are on the CHANGED_FILES list.
   • Impacted Files: Files that are on the BUILD_LIST but not on the CHANGED_FILES list (built due to dependencies).
3. Generates Metadata Records: Creates a PropertiesRecord for each file in the build list with two properties:
   • file: The file path
   • reasonForBuilding: Either "changed" or "impacted"
4. Provides Reporting: In verbose mode, displays detailed statistics including:
   • List of changed files
   • List of impacted files
   • Summary statistics (total changed, total built, impacted count)

Output

Build Report Records

For each file in the build list, a PropertiesRecord is added to the DBB Build Report with the following structure:

PropertiesRecord:
  - file: "MortgageApplication/cobol/epscmort.cbl"
  - reasonForBuilding: "changed"

Console Output (Verbose Mode)

When running in verbose mode (--verbose flag), the task provides detailed output:

> Document reason for building
=== Build Analysis Report ===
==================================================
> Changed Files: 2
--------------------------------------------------
   MortgageApplication/cobol/epscmort.cbl
   MortgageApplication/cobol/epsmlist.cbl
> Impacted Files (built due to dependencies): 1
--------------------------------------------------
   MortgageApplication/cobol/epsmpmt.cbl
=== Summary ===
--------------------------------------------------
Total Changed Files:    2
Total Files Built:      3
Impacted Files:         1
Changed & Built:        2
==================================================

Task Dependencies

This task consumes the following context variables:

• CHANGED_FILES: Set of files that were modified (populated by the ImpactAnalysis task)
• BUILD_LIST: Set of files that were built (populated by the Languages task)

Important: This task must run after both:

1. The ImpactAnalysis task (which populates CHANGED_FILES)
2. The Languages task (which populates BUILD_LIST with all source files built by executed language configurations)

The Languages task is a recommended prerequisite that executes all configured language build tasks and aggregates the built files into the BUILD_LIST context variable.

Additional Notes

• The task is compatible with DBB's build report system and integrates seamlessly into the impact lifecycle.
• Metadata records generated by this task can be consumed by downstream processes such as packaging scripts and deployment tools.
• The task has no impact on the actual build process; it only adds documentation to the build report.
• In non-verbose mode, only summary counts are displayed to minimize console output.