From 8d75c705f560fe87b06a1bd489fd6f5b8bdf95f5 Mon Sep 17 00:00:00 2001
From: Dadisi Sanyika <dadisi@solduara.com>
Date: Tue, 28 Jul 2026 18:19:49 -0700
Subject: [PATCH] feat: add outcome and errors to build.finished

The build finished section of continuous-integration.md states that the
event "will eventually contain the finished status, success, error or
failure", but no such field was ever added to the schema. Because
subject.content sets additionalProperties: false, producers currently
have no conforming way to report whether a build succeeded.

Every other event representing the completion of an execution -
pipelinerun.finished, taskrun.finished, testcaserun.finished and
testsuiterun.finished - already defines outcome with the enum success,
failure, cancel, error. build.finished was the only one without it.

This mirrors pipelinerun.finished exactly, adding both outcome and
errors. Neither is added to required, so the change is backward
compatible: events that omit outcome continue to validate.

Adding fields is a structural, backward compatible change, so the event
version is bumped to a new minor draft (0.3.0 -> 0.4.0-draft) per the
versioning policy, using tools/event-version.sh -u build.finished -s.

Revives #179, which made the same change but was closed for staleness
after a rebase request rather than on merit. Relates to #109.

Signed-off-by: Dadisi Sanyika <dadisi@solduara.com>
---
 conformance/build_finished.json |  5 +++--
 continuous-integration.md       |  6 ++++--
 schemas/buildfinished.json      | 16 ++++++++++++++--
 3 files changed, 21 insertions(+), 6 deletions(-)

diff --git a/conformance/build_finished.json b/conformance/build_finished.json
index 1e19bea..19802ef 100644
--- a/conformance/build_finished.json
+++ b/conformance/build_finished.json
@@ -4,7 +4,7 @@
     "id": "271069a8-fc18-44f1-b38f-9d70a1695819",
     "chainId": "4c8cb7dd-3448-41de-8768-eec704e2829b",
     "source": "/event/source/123",
-    "type": "dev.cdevents.build.finished.0.3.0",
+    "type": "dev.cdevents.build.finished.0.4.0-draft",
     "timestamp": "2023-03-20T14:27:05.315384Z",
     "schemaUri": "https://myorg.com/schema/custom",
     "links": [
@@ -43,7 +43,8 @@
     "id": "mySubject123",
     "source": "/event/source/123",
     "content": {
-      "artifactId": "pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427"
+      "artifactId": "pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427",
+      "outcome": "success"
     }
   }
 }
diff --git a/continuous-integration.md b/continuous-integration.md
index c1c9970..b168b73 100644
--- a/continuous-integration.md
+++ b/continuous-integration.md
@@ -78,9 +78,9 @@ This event represents a Build task that has been started; this build process usu
 
 ### [`build finished`](conformance/build_finished.json)
 
-This event represents a Build task that has finished. This event will eventually contain the finished status, success, error or failure
+A Build task has finished, successfully or not.
 
-- Event Type: __`dev.cdevents.build.finished.0.3.0`__
+- Event Type: __`dev.cdevents.build.finished.0.4.0-draft`__
 - Predicate: finished
 - Subject: [`build`](#build)
 
@@ -89,6 +89,8 @@ This event represents a Build task that has finished. This event will eventually
 | id    | `String` | See [id](spec.md#id-subject)| `1234`, `maven123`, `builds/taskrun123` | ✅ |
 | source | `URI-Reference` | See [source](spec.md#source-subject) | | |
 | artifactId | `Purl` | Identifier of the artifact produced by the build | `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427`, `pkg:golang/mygit.com/myorg/myapp@234fd47e07d1004f0aed9c` | `build` | |
+| outcome | `String (enum)` | outcome of a finished `build` | `success`, `failure`, `cancel`, or `error` | `success`, `failure`, `cancel`, `error` |
+| errors | `String` | In case of error, canceled, or failed build, provides details about the failure | `Invalid input param 123`, `Timeout during execution`, `build canceled by user`, `Compilation failed`| |
 
 ### [`artifact packaged`](conformance/artifact_packaged.json)
 
diff --git a/schemas/buildfinished.json b/schemas/buildfinished.json
index 3dfcf5e..caacba9 100644
--- a/schemas/buildfinished.json
+++ b/schemas/buildfinished.json
@@ -20,9 +20,9 @@
         "type": {
           "type": "string",
           "enum": [
-            "dev.cdevents.build.finished.0.3.0"
+            "dev.cdevents.build.finished.0.4.0-draft"
           ],
-          "default": "dev.cdevents.build.finished.0.3.0"
+          "default": "dev.cdevents.build.finished.0.4.0-draft"
         },
         "timestamp": {
           "type": "string",
@@ -66,6 +66,18 @@
           "properties": {
             "artifactId": {
               "type": "string"
+            },
+            "outcome": {
+              "type": "string",
+              "enum": [
+                "success",
+                "failure",
+                "cancel",
+                "error"
+              ]
+            },
+            "errors": {
+              "type": "string"
             }
           },
           "additionalProperties": false,