Add mergeBase field to VCS predicate

Signed-off-by: Aditya Sirish <aditya@saky.in>
in-toto · Sep 11, 2023 · d39f850 · d39f850
1 parent 0475f64
commit d39f850
Show file tree

Hide file tree

Showing 2 changed files with 26 additions and 7 deletions.
diff --git a/protos/in_toto_attestation/predicates/human_review/vcs/v0/vcs.proto b/protos/in_toto_attestation/predicates/human_review/vcs/v0/vcs.proto
@@ -12,11 +12,13 @@ option java_package = "io.github.intoto.attestation.predicates.human_review.vcs.
 message Review {
     repeated in_toto_attestation.v1.ResourceDescriptor reviewers = 1;
 
-    in_toto_attestation.v1.ResourceDescriptor target = 2;
+    in_toto_attestation.v1.ResourceDescriptor targetTip = 2;
 
-    string review_link = 3;
+    in_toto_attestation.v1.ResourceDescriptor mergeBase = 3;
 
-    google.protobuf.Timestamp reviewTime = 4;
+    string review_link = 4;
 
-    google.protobuf.Struct annotations = 5;
+    google.protobuf.Timestamp reviewTime = 5;
+
+    google.protobuf.Struct annotations = 6;
 }
diff --git a/spec/predicates/human-review-vcs.md b/spec/predicates/human-review-vcs.md
@@ -57,7 +57,8 @@ issuing the review.
     "predicateType": "http://in-toto.io/attestation/human-review/vcs/v0.1",
     "predicate": {
         "reviewers": ["<ResourceDescriptor>", ...],
-        "target": "<ResourceDescriptor>",
+        "targetTip": "<ResourceDescriptor>",
+        "mergeBase": "<ResourceDescriptor>",
         "reviewLink": "<LINK TO REVIEW>",
         "reviewTime": "<TIMESTAMP>",
         "annotations": {...}
@@ -81,12 +82,22 @@ review system. Each entry must include immutable information that is always
 mapped to the reviewer. The digest may be skipped in the ResourceDescriptor,
 using the name and URI fields to record the username and immutable ID.
 
-`target` _ResourceDescriptor_, _required_
+`targetTip` _ResourceDescriptor_, _required_
 
 Records the target location for the proposed changeset. In Git repositories, the
 field must contain the base Git reference (i.e., the base branch) AND the
 current commit ID at the tip of that branch.
 
+`mergeBase` _ResourceDescriptor_, _required_
+
+Records the base of the proposed changeset. In Git repositories, three way
+merges are performed using the tip of the topic branch, the tip of the target
+(or base) branch, and the merge base. In a fast-forward merge, the mergeBase is
+the same as tip of the target branch. Using the subject of the attestation, the
+`targetTip`, and the `mergeBase`, the set of changes reviewed can be inferred.
+
+TODO: this is becoming very Git specific.
+
 `reviewLink` _URI_, _optional_
 
 Contains a link to the full review. Useful to point to information that cannot
@@ -122,12 +133,18 @@ to record review system specific fields.
             "name": "lukpueh",
             "uri": "https://api.github.com/user/589324"
         }],
-        "target": {
+        "targetTip": {
             "name": "refs/heads/develop",
             "digest": {
                 "gitCommit": "330500b54433de4f6f9575676b67738b98ba5e54",
             },
         },
+        "mergeBase": {
+            "name": "refs/heads/develop",
+            "digest": {
+                "gitCommit": "60a614f35073cff606ee745d69aef68f24375b23",
+            },
+        },
         "reviewLink": "https://github.com/in-toto/in-toto/pull/503#pullrequestreview-1341209941",
         "reviewTime": "2023-03-15T11:05:00Z",
         "annotations": {