From 4f044e0f8bac88c31868e4ffb9e3eea78fc7a9dc Mon Sep 17 00:00:00 2001
From: adgar <adgar@google.com>
Date: Mon, 23 Nov 2020 13:46:26 -0800
Subject: [PATCH] Document the 'aspect' field in
 TargetConfiguredId/TargetCompletedId BEP.

As aspect usage grows throughout the Bazel ecosystem, their appearance in BEP
output will grow. It is important for BEP consumers to check the 'aspect' field
in these two event IDs to avoid being confused when multiple events appear for
the same target.

RELNOTES: None.
PiperOrigin-RevId: 343921155
---
 .../proto/build_event_stream.proto            | 28 ++++++++++++++++---
 1 file changed, 24 insertions(+), 4 deletions(-)

diff --git a/src/main/java/com/google/devtools/build/lib/buildeventstream/proto/build_event_stream.proto b/src/main/java/com/google/devtools/build/lib/buildeventstream/proto/build_event_stream.proto
index 92810554a77741..ffb79c87881c9d 100644
--- a/src/main/java/com/google/devtools/build/lib/buildeventstream/proto/build_event_stream.proto
+++ b/src/main/java/com/google/devtools/build/lib/buildeventstream/proto/build_event_stream.proto
@@ -98,8 +98,18 @@ message BuildEventId {
   message TargetConfiguredId {
     string label = 1;
 
-    // If not empty, the id refers to the expansion of the target for a given
-    // aspect.
+    // If empty, the id refers to the expansion of the target. If not-empty,
+    // the id refers to the expansion of an aspect applied to the (already
+    // expanded) target.
+    //
+    // For example, when building an apple_binary that depends on proto_library
+    // "//:foo_proto", there will be two TargetConfigured events for
+    // "//:foo_proto":
+    //
+    // 1. An event with an empty aspect, corresponding to actions producing
+    // language-agnostic outputs from the proto_library; and
+    // 2. An event with aspect "ObjcProtoAspect", corresponding to Objective-C
+    // code generation.
     string aspect = 2;
   }
 
@@ -127,8 +137,18 @@ message BuildEventId {
     // The configuration for which the target was built.
     ConfigurationId configuration = 3;
 
-    // If not empty, the id refers to the completion of the target for a given
-    // aspect.
+    // If empty, the id refers to the completion of the target. If not-empty,
+    // the id refers to the completion of an aspect applied to the (already
+    // completed) target.
+    //
+    // For example, when building an apple_binary that depends on proto_library
+    // "//:foo_proto", there will be two TargetCompleted events for
+    // "//:foo_proto":
+    //
+    // 1. An event with an empty aspect, corresponding to actions producing
+    // language-agnostic outputs from the proto_library; and
+    // 2. An event with aspect "ObjcProtoAspect", corresponding to Objective-C
+    // code generation.
     string aspect = 2;
   }