docs: define the URI as the unit of change

api/base/change/proto/change.proto

@@ -41,5 +41,13 @@ message Change {
     //
     // The commit SHA must be the full 40-character lowercase hex SHA; abbreviated
     // SHAs are rejected because downstream staleness checks compare by strict equality.
+    //
+    // One URI is one unit of change -- a single pull request, revision, or
+    // commit -- and it is the granularity everything downstream operates at. A
+    // list is therefore an ordered set of distinct changes (a stack), not one
+    // change described several ways: they are applied in the order given, each
+    // on top of the last, and each yields its own result. An integration
+    // strategy chosen for a change applies to every URI in the list, the same
+    // way to each.
     repeated string uris = 1;
 }

api/base/mergestrategy/proto/mergestrategy.proto

@@ -27,17 +27,30 @@ option java_package = "com.uber.submitqueue.base.mergestrategy";
 // This is the shared wire contract for merge strategy, reused across SubmitQueue
 // and other repo-local domains — the proto-level analog of the
 // platform/base/mergestrategy Go entity. Domains import it rather than redefining their own.
+//
+// A strategy is chosen once for a change and applies to every URI that change
+// carries, the same way to each. Since one URI is one unit of change (see
+// uber.base.change.Change), the values below are defined per URI: a change
+// carrying three URIs is integrated as three separate applications of the same
+// strategy, in order, not as one combined application.
 enum Strategy {
     // Default strategy (let the server decide based on configuration).
     DEFAULT = 0;
-    // Rebase commits onto the target branch before landing.
+    // Rebase the commits the change introduces onto the target branch before landing.
     REBASE = 1;
-    // Same as REBASE but squash commits into a single commit before rebase.
+    // Same as REBASE, then squash into a single commit. The squash unit is the
+    // individual change: a change of ten commits becomes one commit, and a
+    // stack of three URIs becomes three commits rather than one, so the
+    // boundary between the stacked changes survives.
     SQUASH_REBASE = 2;
-    // Merge commits into the target branch by creating a separate merge commit, preserving commit history along with hashes.
+    // Merge into the target branch by creating a separate merge commit, preserving commit history along with hashes.
     MERGE = 3;
     // Integrate the exact revision as-is, with no content transform — advance the target branch to an already-existing
     // commit rather than producing new revisions. The implementer maps it to its backend: git fast-forward, Mercurial
     // bookmark advance, Subversion/Perforce copy. Used to promote an already-landed/verified commit onto another branch.
+    //
+    // The one strategy that constrains the list rather than repeating over it:
+    // advancing a ref to an exact revision admits a single URI, because a
+    // second one could not also be the revision the target ends at.
     PROMOTE = 4;
 }

api/runway/messagequeue/proto/merge.proto

@@ -36,10 +36,14 @@ message MergeStep {
     // StepResult so a multi-step result is attributable -- and never interprets
     // its contents.
     string step_id = 1;
-    // change is the code change to apply for this step. A change may carry
-    // multiple URIs when the step represents stacked or grouped changes.
+    // change is the code change to apply for this step. It may carry multiple
+    // URIs, which are a stack: each URI is its own unit of change, applied in
+    // the order given, each on top of the last.
     uber.base.change.Change change = 2;
     // strategy is how this step's change is integrated into the merge target.
+    // It applies to every URI the change carries, the same way to each, so a
+    // step is never a mix of strategies. PROMOTE is the exception that admits
+    // only a single URI.
     uber.base.mergestrategy.Strategy strategy = 3;
 }
 

api/submitqueue/gateway/proto/gateway.proto

@@ -57,6 +57,8 @@ message LandRequest {
     // Change (such as a pull request) to land into the target branch. Target branch is defined by the queue configuration.
     uber.base.change.Change change = 2;
     // Source control integration strategy to use for this land operation. If not specified, the default queue strategy is used.
+    // It applies to every URI the change carries, the same way to each — a land
+    // request cannot pick a different strategy per URI.
     uber.base.mergestrategy.Strategy strategy = 4;
 }
 

platform/base/change/change.go

@@ -32,5 +32,11 @@ type Change struct {
 	//
 	// Head/commit SHAs must be the full 40-char lowercase hex form.
 	//
+	// One URI is one unit of change — a single pull request, revision, or
+	// commit. A list is an ordered set of distinct changes (a stack), not one
+	// change described several ways: order is significant, each entry applies
+	// on top of the last, and each yields its own result. An integration
+	// strategy chosen for a change applies to every URI in the list, the same
+	// way to each.
 	URIs []string `json:"uris"`
 }

runway/extension/merger/git/README.md

@@ -6,6 +6,8 @@ A `merger.Merger` backed by the `git` CLI operating on a local checkout. It appl
 
 A request is an ordered list of steps; each step names a change (a set of provider URIs, each ending in a full head commit SHA) and a strategy. Steps are applied in order on top of the target tip — earlier steps are the in-flight base, the last step is the candidate. Each step yields one `StepResult`; the revisions a step produces on the target are its outputs, in application order.
 
+The URI is the unit of application. A step's change may carry several URIs — a stack — and the step's strategy applies to each of them, the same way to each, in the order given. So a step is never a mix of strategies, and its outputs are the concatenation of what each URI produced: one revision per created commit under `REBASE`, one per URI under `SQUASH_REBASE` and `MERGE`. `PROMOTE` is the exception that admits only one URI, since advancing a ref to an exact revision cannot repeat.
+
 A URI pins a change to one head commit, but a change is routinely several commits. The full set is recovered locally rather than from the wire: the commits to replay are the range from the change's merge base with the target up to its head. Applying the head commit alone would apply only that commit's diff against its own parent — conflicting against context its predecessors would have established, or silently dropping them when they touch different files.
 
 ## Change providers

submitqueue/entity/land.go

@@ -31,7 +31,8 @@ type LandRequest struct {
 	Queue string `json:"queue"`
 	// Change is the set of code changes to land.
 	Change change.Change `json:"change"`
-	// LandStrategy is the source control integration strategy to use for this land operation.
+	// LandStrategy is the source control integration strategy to use for this
+	// land operation. It applies to every URI of Change, the same way to each.
 	LandStrategy mergestrategy.MergeStrategy `json:"land_strategy"`
 }
 

submitqueue/entity/request.go

@@ -82,7 +82,8 @@ type Request struct {
 	Queue string `json:"queue"`
 	// Change is a number of code changes (such as pull requests) to land into the target branch. Target branch is defined by the queue configuration.
 	Change change.Change `json:"change"`
-	// LandStrategy is the source control integration strategy to use for this land operation.
+	// LandStrategy is the source control integration strategy to use for this
+	// land operation. It applies to every URI of Change, the same way to each.
 	LandStrategy mergestrategy.MergeStrategy `json:"land_strategy"`
 
 	// ****************