Update the contract of command line tools

[erichaagdev]

❄️ Winter Update PR Navigator ❄️

1. Include realized build time savings in experiment summary #261
2. Include performance characteristics and support -x for Gradle experiment 1  #262
3. Always read project name from Build Scan data #263
4. Gradle init script improvements #264
5. Adopt Foojay Toolchains and Kotlin DSL plugins in build logic #265
6. Add variable to query debug mode #266
7. Modernize Java launch code #267
8. Display serialization factor in summary of all experiments #272
9. Display potential build time savings in experiment summaries #274
10. ⛄ Update the contract of command line tools #283

⛄ = you are here

Summary

This PR cleans up and simplifies the contract of the Build Scan CSV sent by the command line tools. This is the final PR for implementing #206.

ℹ️ This PR is related to gradle/ge#19681 which contains the corresponding changes to support offline processing.

Examples:

Testing

To test this, I ran all of the following experiments and examined their output was as expected. For those experiments using -x, I used the latest version of the build-scan-support-tool based on the changes in gradle/ge#19681.

./01-validate-incremental-building.sh -r git@github.com:gradle/androidx.git -p biometric -t 'buildOnServer' -s https://ge.solutions-team.gradle.com -x
./02-validate-local-build-caching-same-location.sh -r git@github.com:gradle/androidx.git -p biometric -t 'buildOnServer' -s https://ge.solutions-team.gradle.com -x
./03-validate-local-build-caching-different-locations.sh -r git@github.com:gradle/androidx.git -p biometric -t 'buildOnServer' -s https://ge.solutions-team.gradle.com -x
./01-validate-local-build-caching-same-location.sh -r git@github.com:OpenAPITools/openapi-generator.git -g 'package' -a '-DskipTests' -e -s https://ge.solutions-team.gradle.com -x
./02-validate-local-build-caching-different-locations.sh -r git@github.com:OpenAPITools/openapi-generator.git -g 'package' -a '-DskipTests' -e -s https://ge.solutions-team.gradle.com -x
./01-validate-incremental-building.sh -r git@github.com:gradle/androidx.git -p biometric -t 'buildOnServer' -s https://ge.solutions-team.gradle.com
./02-validate-local-build-caching-same-location.sh -r git@github.com:gradle/androidx.git -p biometric -t 'buildOnServer' -s https://ge.solutions-team.gradle.com
./03-validate-local-build-caching-different-locations.sh -r git@github.com:gradle/androidx.git -p biometric -t 'buildOnServer' -s https://ge.solutions-team.gradle.com
./04-validate-remote-build-caching-ci-ci.sh -1 https://ge.solutions-team.gradle.com/s/4jmo6kqqjnebg -2 https://ge.solutions-team.gradle.com/s/5bwb5ofenxrts
./01-validate-local-build-caching-same-location.sh -r git@github.com:OpenAPITools/openapi-generator.git -g 'package' -a '-DskipTests' -e -s https://ge.solutions-team.gradle.com
./02-validate-local-build-caching-different-locations.sh -r git@github.com:OpenAPITools/openapi-generator.git -g 'package' -a '-DskipTests' -e -s https://ge.solutions-team.gradle.com
./03-validate-remote-build-caching-ci-ci.sh -1 https://ge.solutions-team.gradle.com/s/cdfz7q2whfxia -2 https://ge.solutions-team.gradle.com/s/2elplm2ff76am

[jthurne]

This PR contains breaking changes and should not be merged until the build-scan-support-tool is updated to support #206.

They are not breaking changes from an end-user perspective. These are just breaking changes to our internal contract between the build validation scripts and the utilities which read the Build Scan data. I make this comment because this change does not necessitate bumping the major version of the build validation scripts.

[jthurne]

This PR contains breaking changes and should not be merged until the build-scan-support-tool is updated to support #206.

They are not breaking changes from an end-user perspective. These are just breaking changes to our internal contract between the build validation scripts and the utilities which read the Build Scan data. I make this comment because this change does not necessitate bumping the major version of the build validation scripts.

I just remembered that we distribute build-scan-support-tools separately from the scripts. So while this is an update to an internal private API, it does mean that newer versions of the build validation scripts will be incompatible with earlier versions of the build-scan-support-tools. This is fine if we haven't given the build-scan-support-tools to anyone yet. But if we have, we may want to start keeping a compatibility matrix to show which versions of the build-scan-support-tools are compatible with which versions of the build validation scripts.

[jthurne]

This cleans things up nicely. It would be good to update build-scan-support-tools soon so that we can merge this with the other PRs.

[erichaagdev]

This is fine if we haven't given the build-scan-support-tools to anyone yet. But if we have, we may want to start keeping a compatibility matrix to show which versions of the build-scan-support-tools are compatible with which versions of the build validation scripts.

I don't believe we've distributed it yet. I do have similar concerns on how to best handle the versioning between all tools (Gradle Enterprise version, Gradle version, CLI tools, and the scripts themselves).