From aab7e64eb4df870e6d857861e6cf111f6c72387c Mon Sep 17 00:00:00 2001 From: "kevin.new" Date: Tue, 30 Jun 2026 21:28:35 +0000 Subject: [PATCH] refactor(runway): use "merge target" terminology consistently Replace "target branch" and "landing target" with "merge target" throughout runway's merger extension, message queue contract, proto definitions, and documentation. "Branch" is git-specific; the system is VCS-neutral. --- api/runway/messagequeue/README.md | 6 +++--- api/runway/messagequeue/merge.go | 2 +- api/runway/messagequeue/proto/merge.proto | 14 +++++++------- api/runway/messagequeue/protopb/merge.pb.go | 14 +++++++------- runway/extension/merger/merger.go | 10 +++++----- 5 files changed, 23 insertions(+), 23 deletions(-) diff --git a/api/runway/messagequeue/README.md b/api/runway/messagequeue/README.md index 0f32751d..d9aaf161 100644 --- a/api/runway/messagequeue/README.md +++ b/api/runway/messagequeue/README.md @@ -8,7 +8,7 @@ The shared field types `Change` and `MergeStrategy` come from `api/base/change` ## Merge strategy -Each `MergeStep` carries a `Strategy` (from `api/base/mergestrategy`) naming how that step is integrated into the target branch. `REBASE`, `SQUASH_REBASE`, and `MERGE` *transform* the change onto the branch tip and produce new revisions. `PROMOTE` is different: it integrates the exact revision **as-is**, advancing the target branch to an already-existing commit with no content transform and no new revision. Each backend realizes `PROMOTE` natively — git fast-forward, Mercurial bookmark advance, Subversion/Perforce copy — so for `PROMOTE` a step's `StepOutput.id` is the same revision the request named rather than a freshly created one. It is the strategy a post-merge verifier (e.g. Stovepipe) uses to advance a verified branch like `verified/main` to an already-landed, already-verified commit. `DEFAULT` lets the server pick per queue configuration. +Each `MergeStep` carries a `Strategy` (from `api/base/mergestrategy`) naming how that step is integrated into the merge target. `REBASE`, `SQUASH_REBASE`, and `MERGE` *transform* the change onto the branch tip and produce new revisions. `PROMOTE` is different: it integrates the exact revision **as-is**, advancing the merge target to an already-existing commit with no content transform and no new revision. Each backend realizes `PROMOTE` natively — git fast-forward, Mercurial bookmark advance, Subversion/Perforce copy — so for `PROMOTE` a step's `StepOutput.id` is the same revision the request named rather than a freshly created one. It is the strategy a post-merge verifier (e.g. Stovepipe) uses to advance a verified branch like `verified/main` to an already-landed, already-verified commit. `DEFAULT` lets the server pick per queue configuration. ## Topic keys @@ -19,11 +19,11 @@ The binding between a topic key and its payload lives in each message's `topic_k | `MergeRequest` | client → Runway | `merge-conflict-check`, `merge` | | `MergeResult` | Runway → client | `merge-conflict-check-signal`, `merge-signal` | -One message serves a queue pair because a merge-conflict check is a dry run of a merge: Runway applies the same ordered steps onto the same target branch, and the topic key the request arrives on decides whether it commits the result and reports the produced revisions. A request on `merge-conflict-check` is a dry run; a request on `merge` commits. +One message serves a queue pair because a merge-conflict check is a dry run of a merge: Runway applies the same ordered steps onto the same merge target, and the topic key the request arrives on decides whether it commits the result and reports the produced revisions. A request on `merge-conflict-check` is a dry run; a request on `merge` commits. ## Result shape -`MergeResult.outcome` is an `Outcome` enum (`OUTCOME_UNSPECIFIED`/`SUCCEEDED`/`FAILED`): `SUCCEEDED` means mergeable (check) or merged (commit), `FAILED` a conflict or a failed apply; `reason` carries the explanation when `FAILED`. Per-step detail is in `steps` (request order): each `StepResult.outputs` is the list of `StepOutput`s the step produced on the target branch, **in application order** (the order they were created). A committing merge populates `outputs`; a dry-run check, an already-present change, or a failed step leaves them empty. `StepOutput.id` is the VCS-neutral revision identifier (git SHA, Mercurial hash, Subversion revision, Perforce changelist, …), with room to grow (author, timestamp, …). +`MergeResult.outcome` is an `Outcome` enum (`OUTCOME_UNSPECIFIED`/`SUCCEEDED`/`FAILED`): `SUCCEEDED` means mergeable (check) or merged (commit), `FAILED` a conflict or a failed apply; `reason` carries the explanation when `FAILED`. Per-step detail is in `steps` (request order): each `StepResult.outputs` is the list of `StepOutput`s the step produced on the merge target, **in application order** (the order they were created). A committing merge populates `outputs`; a dry-run check, an already-present change, or a failed step leaves them empty. `StepOutput.id` is the VCS-neutral revision identifier (git SHA, Mercurial hash, Subversion revision, Perforce changelist, …), with room to grow (author, timestamp, …). ## Evolution diff --git a/api/runway/messagequeue/merge.go b/api/runway/messagequeue/merge.go index 4022cb7a..69184a99 100644 --- a/api/runway/messagequeue/merge.go +++ b/api/runway/messagequeue/merge.go @@ -56,7 +56,7 @@ type ( MergeResult = protopb.MergeResult // StepResult reports what happened to a single MergeStep. StepResult = protopb.StepResult - // StepOutput is a single revision a merge step produced on the target branch. + // StepOutput is a single revision a merge step produced on the merge target. StepOutput = protopb.StepOutput ) diff --git a/api/runway/messagequeue/proto/merge.proto b/api/runway/messagequeue/proto/merge.proto index 97ea68fe..b2805f03 100644 --- a/api/runway/messagequeue/proto/merge.proto +++ b/api/runway/messagequeue/proto/merge.proto @@ -27,7 +27,7 @@ option java_package = "com.uber.submitqueue.runway.messagequeue"; // MergeStep is one step of an ordered merge: a single set of change(s) applied // with a strategy. Runway applies the steps of a request in order on top of the -// target branch; the ordering encodes the base-layering (earlier steps are the +// merge target; the ordering encodes the base-layering (earlier steps are the // in-flight base, the last step is the candidate). message MergeStep { // step_id is an opaque, caller-assigned identifier for this step. Runway @@ -37,7 +37,7 @@ message MergeStep { string step_id = 1; // changes are the code change(s) to apply for this step. repeated uber.base.change.Change changes = 2; - // strategy is how this step's changes are integrated into the target branch. + // strategy is how this step's changes are integrated into the merge target. uber.base.mergestrategy.Strategy strategy = 3; } @@ -54,16 +54,16 @@ message MergeRequest { // Runway echoes it back on the result unchanged. string id = 1; // queue_name is the caller-provided queue name the request belongs to. - // Runway resolves the target branch and provider config per-queue from this + // Runway resolves the merge target and provider config per-queue from this // name; no target ref is passed. string queue_name = 2; // steps is the ordered application sequence: in-flight steps first, the - // candidate last. A single-element list expresses "candidate vs target - // branch". + // candidate last. A single-element list expresses "candidate vs merge + // target". repeated MergeStep steps = 3; } -// StepOutput is a single output a merge step produced on the target branch. +// StepOutput is a single output a merge step produced on the merge target. message StepOutput { // id is the VCS-neutral revision identifier -- a git commit SHA, a Mercurial // changeset hash, a Subversion revision number, a Perforce changelist, and so @@ -77,7 +77,7 @@ message StepOutput { message StepResult { // step_id echoes the step_id of the step this result is for. string step_id = 1; - // outputs are the revisions this step produced on the target branch, in + // outputs are the revisions this step produced on the merge target, in // application order (the order the step created them on the target). Empty // for a dry-run check, for a change already present on the target, or for a // step that failed to apply. diff --git a/api/runway/messagequeue/protopb/merge.pb.go b/api/runway/messagequeue/protopb/merge.pb.go index b8cedd4d..80785e48 100644 --- a/api/runway/messagequeue/protopb/merge.pb.go +++ b/api/runway/messagequeue/protopb/merge.pb.go @@ -97,7 +97,7 @@ func (Outcome) EnumDescriptor() ([]byte, []int) { // MergeStep is one step of an ordered merge: a single set of change(s) applied // with a strategy. Runway applies the steps of a request in order on top of the -// target branch; the ordering encodes the base-layering (earlier steps are the +// merge target; the ordering encodes the base-layering (earlier steps are the // in-flight base, the last step is the candidate). type MergeStep struct { state protoimpl.MessageState `protogen:"open.v1"` @@ -108,7 +108,7 @@ type MergeStep struct { StepId string `protobuf:"bytes,1,opt,name=step_id,json=stepId,proto3" json:"step_id,omitempty"` // changes are the code change(s) to apply for this step. Changes []*protopb.Change `protobuf:"bytes,2,rep,name=changes,proto3" json:"changes,omitempty"` - // strategy is how this step's changes are integrated into the target branch. + // strategy is how this step's changes are integrated into the merge target. Strategy protopb1.Strategy `protobuf:"varint,3,opt,name=strategy,proto3,enum=uber.base.mergestrategy.Strategy" json:"strategy,omitempty"` unknownFields protoimpl.UnknownFields sizeCache protoimpl.SizeCache @@ -176,12 +176,12 @@ type MergeRequest struct { // Runway echoes it back on the result unchanged. Id string `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"` // queue_name is the caller-provided queue name the request belongs to. - // Runway resolves the target branch and provider config per-queue from this + // Runway resolves the merge target and provider config per-queue from this // name; no target ref is passed. QueueName string `protobuf:"bytes,2,opt,name=queue_name,json=queueName,proto3" json:"queue_name,omitempty"` // steps is the ordered application sequence: in-flight steps first, the - // candidate last. A single-element list expresses "candidate vs target - // branch". + // candidate last. A single-element list expresses "candidate vs merge + // target". Steps []*MergeStep `protobuf:"bytes,3,rep,name=steps,proto3" json:"steps,omitempty"` unknownFields protoimpl.UnknownFields sizeCache protoimpl.SizeCache @@ -238,7 +238,7 @@ func (x *MergeRequest) GetSteps() []*MergeStep { return nil } -// StepOutput is a single output a merge step produced on the target branch. +// StepOutput is a single output a merge step produced on the merge target. type StepOutput struct { state protoimpl.MessageState `protogen:"open.v1"` // id is the VCS-neutral revision identifier -- a git commit SHA, a Mercurial @@ -292,7 +292,7 @@ type StepResult struct { state protoimpl.MessageState `protogen:"open.v1"` // step_id echoes the step_id of the step this result is for. StepId string `protobuf:"bytes,1,opt,name=step_id,json=stepId,proto3" json:"step_id,omitempty"` - // outputs are the revisions this step produced on the target branch, in + // outputs are the revisions this step produced on the merge target, in // application order (the order the step created them on the target). Empty // for a dry-run check, for a change already present on the target, or for a // step that failed to apply. diff --git a/runway/extension/merger/merger.go b/runway/extension/merger/merger.go index cbade471..9a77963a 100644 --- a/runway/extension/merger/merger.go +++ b/runway/extension/merger/merger.go @@ -14,7 +14,7 @@ // Package merger defines the pluggable interface for version-control merge // operations that Runway performs on behalf of its callers. Implementations -// resolve change URIs, apply changes to a target branch, and (for a committing +// resolve change URIs, apply changes to a merge target, and (for a committing // merge) push the result and finalize the change lifecycle (e.g. close PRs). package merger @@ -32,7 +32,7 @@ import ( // result), not an infrastructure error. var ErrConflict = errors.New("merge conflict") -// Merger performs version-control operations against a single landing target. +// Merger performs version-control operations against a single merge target. // Both methods accept the same MergeRequest payload; the behavioral difference // is whether the result is committed to the remote. type Merger interface { @@ -44,15 +44,15 @@ type Merger interface { Merge(ctx context.Context, req *runwaymq.MergeRequest) (*runwaymq.MergeResult, error) } -// Config identifies the landing target a Merger instance operates on. The factory +// Config identifies the merge target a Merger instance operates on. The factory // resolves deployment-specific details (remote URL, credentials) from this. type Config struct { // QueueName is the caller-provided queue name from the MergeRequest. QueueName string } -// Factory creates Merger instances bound to a landing target. +// Factory creates Merger instances bound to a merge target. type Factory interface { - // For returns a Merger instance configured for the given landing target. + // For returns a Merger instance configured for the given merge target. For(cfg Config) (Merger, error) }