From 7825c3d480ebee522345cbcc90a2ff76c6353d88 Mon Sep 17 00:00:00 2001 From: Joshua Watt Date: Wed, 4 Sep 2024 15:46:40 -0600 Subject: [PATCH] build: Clarify buildType Clarifies the meaning of buildType, as it was unclear. The actual intent was to "namespace" the meaning of a Build element so that the rest of the properties can be interpreted. This matches the SLSA definition of buildType. --- model/Build/Properties/buildId.md | 2 +- model/Build/Properties/buildType.md | 27 +++++++++++++++---- model/Build/Properties/configSourceDigest.md | 2 +- .../Properties/configSourceEntrypoint.md | 2 +- model/Build/Properties/configSourceUri.md | 3 ++- model/Build/Properties/environment.md | 2 +- model/Build/Properties/parameter.md | 2 +- 7 files changed, 29 insertions(+), 11 deletions(-) diff --git a/model/Build/Properties/buildId.md b/model/Build/Properties/buildId.md index 679d423eb..9c272df1c 100644 --- a/model/Build/Properties/buildId.md +++ b/model/Build/Properties/buildId.md @@ -10,7 +10,7 @@ instance of a build produced by it. ## Description A buildId is a locally unique identifier to identify a unique instance of a -build. +build, according to the buildType. This identifier differs based on build toolchain, platform, or naming convention used by an organization or standard. diff --git a/model/Build/Properties/buildType.md b/model/Build/Properties/buildType.md index 00a62ad15..379c8009a 100644 --- a/model/Build/Properties/buildType.md +++ b/model/Build/Properties/buildType.md @@ -9,13 +9,30 @@ infrastructure that the build was invoked on. ## Description -A buildType is a URI expressing the toolchain, platform, or infrastructure that +A buildType is a IRI expressing the toolchain, platform, or infrastructure that the build was invoked on. -For example, if the build was invoked on GitHub's CI platform using GitHub -Actions, the buildType can be expressed as `https://github.com/actions`. -In contrast, if the build was invoked on a local machine, the buildType can be -expressed as `file://username@host/path/to/build`. +The buildType is used to interpret the meaning of other build parameters by +defining the "type" of build; if the same buildType is seen in different Build +elements, it means they are the same kind of build, but difference instances +and possible with different configurations. + +If you are not using a well-known buildType, it should be namespaced to a +domain you own to prevent conflicts with other builtType IRIs. + +Examples of a buildType might be: +* A GitHub action workflow +* A step in a GitHub actions pipeline +* An invocation of a compiler or other tool +* A script that orchestrates builds at a higher level + +Keep in mind that builds can be "nested" using the `ancestorOf` relationship + +If the buildType IRI is not recognized, it is still possible to inspect other +properties of the build, but it may not be possible to derive deeper meaning +from them + +For more information, see the SLSA definition of buildType ## Metadata diff --git a/model/Build/Properties/configSourceDigest.md b/model/Build/Properties/configSourceDigest.md index 408acf3fc..949d2d20f 100644 --- a/model/Build/Properties/configSourceDigest.md +++ b/model/Build/Properties/configSourceDigest.md @@ -10,7 +10,7 @@ invoke a build. ## Description configSourceDigest is the checksum of the build configuration file used by a -builder to execute a build. +builder to execute a build, according to the buildType. This Property uses the Core model's [Hash](../../Core/Classes/Hash.md) class. diff --git a/model/Build/Properties/configSourceEntrypoint.md b/model/Build/Properties/configSourceEntrypoint.md index cd8d2500b..bacaa81a2 100644 --- a/model/Build/Properties/configSourceEntrypoint.md +++ b/model/Build/Properties/configSourceEntrypoint.md @@ -9,7 +9,7 @@ Property describes the invocation entrypoint of a build. ## Description A build entrypoint is the invoked executable of a build which always runs when -the build is triggered. +the build is triggered, according to the buildType. For example, when a build is triggered by running a shell script, the entrypoint is `script.sh`. diff --git a/model/Build/Properties/configSourceUri.md b/model/Build/Properties/configSourceUri.md index 96b097445..d46b27091 100644 --- a/model/Build/Properties/configSourceUri.md +++ b/model/Build/Properties/configSourceUri.md @@ -9,7 +9,8 @@ Property that describes the URI of the build configuration source file. ## Description If a build configuration exists for the toolchain or platform performing the -build, the configSourceUri of a build is the URI of that build configuration. +build, the configSourceUri of a build is the URI of that build configuration, +according to the buildType. For example, a build triggered by a GitHub Action is defined by a build configuration YAML file. In this case, the configSourceUri is the URL of that diff --git a/model/Build/Properties/environment.md b/model/Build/Properties/environment.md index caeeb852f..8fcbf94e6 100644 --- a/model/Build/Properties/environment.md +++ b/model/Build/Properties/environment.md @@ -9,7 +9,7 @@ Property describing the session in which a build is invoked. ## Description environment is a map of environment variables and values that are set during a -build session. +build session, according to the buildType. This is different from the [parameter](parameter.md) property in that it describes the environment variables set before a build is invoked rather than diff --git a/model/Build/Properties/parameter.md b/model/Build/Properties/parameter.md index 9f6b56fe8..4ae28fc38 100644 --- a/model/Build/Properties/parameter.md +++ b/model/Build/Properties/parameter.md @@ -9,7 +9,7 @@ Property describing a parameter used in an instance of a build. ## Description parameter is a key-value of a build parameter and its value that -was provided to the builder for a build instance. +was provided to the builder for a build instance, according to the buildType. This is different from the [environment](environment.md) property in that the key and value are provided as command line arguments or