internal/task, gerrit: create a new branch for minor release

1. Add new method CreateBranch to interface GerritClient.
   a. Implement CreateBranch real gerrit client follow gerrit
   documentation.
   b. Implement CreateBranch using git branch for fake client.
2. Change fake gerrit client implementation of ReadBranchHead to
   return empty string if encounter error to align return value with
   the real client.
3. Change return type of isValidVersion to semantic version to avoid
   future code duplication.
4. Add a new action CreateBranchIfMinor to gopls release after
   converting the input version string to semantic version struct.

A local relui screenshot is at https://go.dev/issue/57643#issuecomment-2258617146.

For golang/go#57643

Change-Id: I36eb88625ed6036eb322c39b345aee3f1ffa3f5c
Reviewed-on: https://go-review.googlesource.com/c/build/+/601655
Reviewed-by: Dmitri Shuralyov <[email protected]>
Reviewed-by: Dmitri Shuralyov <[email protected]>
LUCI-TryBot-Result: Go LUCI <[email protected]>

Author: h9jiang

gerrit/gerrit.go

@@ -844,6 +844,14 @@ type BranchInfo struct {
 	CanDelete bool   `json:"can_delete"`
 }
 
+// The BranchInput entity contains information for the creation of a new branch.
+// See https://gerrit-review.googlesource.com/Documentation/rest-api-projects.html#branch-input
+type BranchInput struct {
+	Ref      string `json:"ref,omitempty"`
+	Revision string `json:"revision,omitempty"`
+	// ValidationOptions is optional.
+}
+
 // GetProjectBranches returns the branches for the project name. The branches are stored in a map
 // keyed by reference.
 func (c *Client) GetProjectBranches(ctx context.Context, name string) (map[string]BranchInfo, error) {
@@ -868,6 +876,15 @@ func (c *Client) GetBranch(ctx context.Context, project, branch string) (BranchI
 	return res, err
 }
 
+// CreateBranch create a new branch in the project.
+//
+// See https://gerrit-review.googlesource.com/Documentation/rest-api-projects.html#create-branch
+func (c *Client) CreateBranch(ctx context.Context, project, branch string, input BranchInput) (BranchInfo, error) {
+	var res BranchInfo
+	err := c.do(ctx, &res, "PUT", fmt.Sprintf("/projects/%s/branches/%s", url.PathEscape(project), url.PathEscape(branch)), reqBodyJSON{&input}, wantResStatus(http.StatusCreated))
+	return res, err
+}
+
 // GetFileContent gets a file's contents at a particular commit.
 //
 // See https://gerrit-review.googlesource.com/Documentation/rest-api-projects.html#get-content-from-commit.

internal/task/fakes.go

@@ -220,7 +220,24 @@ func (g *FakeGerrit) ReadBranchHead(ctx context.Context, project, branch string)
 	}
 	// TODO: If the branch doesn't exist, return an error matching gerrit.ErrResourceNotExist.
 	out, err := repo.dir.RunCommand(ctx, "rev-parse", "refs/heads/"+branch)
-	return strings.TrimSpace(string(out)), err
+	if err != nil {
+		// Returns empty string if the error is nil to align the same behavior with
+		// the real Gerrit client.
+		return "", err
+	}
+	return strings.TrimSpace(string(out)), nil
+}
+
+func (g *FakeGerrit) CreateBranch(ctx context.Context, project, branch string, input gerrit.BranchInput) (string, error) {
+	repo, err := g.repo(project)
+	if err != nil {
+		return "", err
+	}
+	if _, err = repo.dir.RunCommand(ctx, "branch", branch, input.Revision); err != nil {
+		return "", err
+	}
+
+	return g.ReadBranchHead(ctx, project, branch)
 }
 
 func (g *FakeGerrit) ReadFile(ctx context.Context, project string, commit string, file string) ([]byte, error) {

internal/task/gerrit.go

@@ -38,6 +38,8 @@ type GerritClient interface {
 	// ReadBranchHead returns the head of a branch in project.
 	// If the branch doesn't exist, it returns an error matching gerrit.ErrResourceNotExist.
 	ReadBranchHead(ctx context.Context, project, branch string) (string, error)
+	// CreateBranch create the given branch and returns the created branch's revision.
+	CreateBranch(ctx context.Context, project, branch string, input gerrit.BranchInput) (string, error)
 	// ListProjects lists all the projects on the server.
 	ListProjects(ctx context.Context) ([]string, error)
 	// ReadFile reads a file from project at the specified commit.
@@ -194,6 +196,14 @@ func (c *RealGerritClient) ReadBranchHead(ctx context.Context, project, branch s
 	return branchInfo.Revision, nil
 }
 
+func (c *RealGerritClient) CreateBranch(ctx context.Context, project, branch string, input gerrit.BranchInput) (string, error) {
+	branchInfo, err := c.Client.CreateBranch(ctx, project, branch, input)
+	if err != nil {
+		return "", err
+	}
+	return branchInfo.Revision, nil
+}
+
 func (c *RealGerritClient) ListProjects(ctx context.Context) ([]string, error) {
 	projects, err := c.Client.ListProjects(ctx)
 	if err != nil {

internal/task/releasegopls.go

@@ -9,6 +9,7 @@ import (
 	"slices"
 	"strings"
 
+	"golang.org/x/build/gerrit"
 	wf "golang.org/x/build/internal/workflow"
 	"golang.org/x/mod/semver"
 )
@@ -26,36 +27,71 @@ func (r *ReleaseGoplsTasks) NewDefinition() *wf.Definition {
 	// TODO(hxjiang): provide potential release versions in the relui where the
 	// coordinator can choose which version to release instead of manual input.
 	version := wf.Param(wd, wf.ParamDef[string]{Name: "version"})
-	isValid := wf.Task1(wd, "validating input version", r.isValidVersion, version)
-	wf.Output(wd, "valid", isValid)
+	semversion := wf.Task1(wd, "validating input version", r.isValidVersion, version)
+	_ = wf.Action1(wd, "creating new branch if minor release", r.createBranchIfMinor, semversion)
 	return wd
 }
 
-func (r *ReleaseGoplsTasks) isValidVersion(ctx *wf.TaskContext, ver string) (bool, error) {
+// createBranchIfMinor create the release branch if the input version is a minor
+// release.
+// All patch releases under the same minor version share the same release branch.
+func (r *ReleaseGoplsTasks) createBranchIfMinor(ctx *wf.TaskContext, semv semversion) error {
+	branch := fmt.Sprintf("gopls-release-branch.%v.%v", semv.Major, semv.Minor)
+
+	// Require gopls release branch existence if this is a non-minor release.
+	if semv.Patch != 0 {
+		_, err := r.Gerrit.ReadBranchHead(ctx, "tools", branch)
+		return err
+	}
+
+	// Return early if the branch already exist.
+	// This scenario should only occur if the initial minor release flow failed
+	// or was interrupted and subsequently re-triggered.
+	if _, err := r.Gerrit.ReadBranchHead(ctx, "tools", branch); err == nil {
+		return nil
+	}
+
+	// Create the release branch using the revision from the head of master branch.
+	head, err := r.Gerrit.ReadBranchHead(ctx, "tools", "master")
+	if err != nil {
+		return err
+	}
+
+	ctx.Printf("Creating branch %s at revision %s.\n", branch, head)
+	_, err = r.Gerrit.CreateBranch(ctx, "tools", branch, gerrit.BranchInput{Revision: head})
+	return err
+}
+
+func (r *ReleaseGoplsTasks) isValidVersion(ctx *wf.TaskContext, ver string) (semversion, error) {
 	if !semver.IsValid(ver) {
-		return false, nil
+		return semversion{}, fmt.Errorf("the input %q version does not follow semantic version schema", ver)
 	}
 
 	versions, err := r.possibleGoplsVersions(ctx)
 	if err != nil {
-		return false, fmt.Errorf("failed to get latest Gopls version tags from x/tool: %w", err)
+		return semversion{}, fmt.Errorf("failed to get latest Gopls version tags from x/tool: %w", err)
+	}
+
+	if !slices.Contains(versions, ver) {
+		return semversion{}, fmt.Errorf("the input %q is not next version of any existing versions", ver)
 	}
 
-	return slices.Contains(versions, ver), nil
+	semver, _ := parseSemver(ver)
+	return semver, nil
 }
 
 // semversion is a parsed semantic version.
 type semversion struct {
-	major, minor, patch int
-	pre                 string
+	Major, Minor, Patch int
+	Pre                 string
 }
 
 // parseSemver attempts to parse semver components out of the provided semver
 // v. If v is not valid semver in canonical form, parseSemver returns false.
 func parseSemver(v string) (_ semversion, ok bool) {
 	var parsed semversion
-	v, parsed.pre, _ = strings.Cut(v, "-")
-	if _, err := fmt.Sscanf(v, "v%d.%d.%d", &parsed.major, &parsed.minor, &parsed.patch); err == nil {
+	v, parsed.Pre, _ = strings.Cut(v, "-")
+	if _, err := fmt.Sscanf(v, "v%d.%d.%d", &parsed.Major, &parsed.Minor, &parsed.Patch); err == nil {
 		ok = true
 	}
 	return parsed, ok
@@ -89,32 +125,32 @@ func (r *ReleaseGoplsTasks) possibleGoplsVersions(ctx *wf.TaskContext) ([]string
 		semv, ok := parseSemver(v)
 		semVersions = append(semVersions, semv)
 
-		if majorMinorPatch[semv.major] == nil {
-			majorMinorPatch[semv.major] = map[int]map[int]bool{}
+		if majorMinorPatch[semv.Major] == nil {
+			majorMinorPatch[semv.Major] = map[int]map[int]bool{}
 		}
-		if majorMinorPatch[semv.major][semv.minor] == nil {
-			majorMinorPatch[semv.major][semv.minor] = map[int]bool{}
+		if majorMinorPatch[semv.Major][semv.Minor] == nil {
+			majorMinorPatch[semv.Major][semv.Minor] = map[int]bool{}
 		}
-		majorMinorPatch[semv.major][semv.minor][semv.patch] = true
+		majorMinorPatch[semv.Major][semv.Minor][semv.Patch] = true
 	}
 
 	var possible []string
 	seen := map[string]bool{}
 	for _, v := range semVersions {
-		nextMajor := fmt.Sprintf("v%d.%d.%d", v.major+1, 0, 0)
-		if _, ok := majorMinorPatch[v.major+1]; !ok && !seen[nextMajor] {
+		nextMajor := fmt.Sprintf("v%d.%d.%d", v.Major+1, 0, 0)
+		if _, ok := majorMinorPatch[v.Major+1]; !ok && !seen[nextMajor] {
 			seen[nextMajor] = true
 			possible = append(possible, nextMajor)
 		}
 
-		nextMinor := fmt.Sprintf("v%d.%d.%d", v.major, v.minor+1, 0)
-		if _, ok := majorMinorPatch[v.major][v.minor+1]; !ok && !seen[nextMinor] {
+		nextMinor := fmt.Sprintf("v%d.%d.%d", v.Major, v.Minor+1, 0)
+		if _, ok := majorMinorPatch[v.Major][v.Minor+1]; !ok && !seen[nextMinor] {
 			seen[nextMinor] = true
 			possible = append(possible, nextMinor)
 		}
 
-		nextPatch := fmt.Sprintf("v%d.%d.%d", v.major, v.minor, v.patch+1)
-		if _, ok := majorMinorPatch[v.major][v.minor][v.patch+1]; !ok && !seen[nextPatch] {
+		nextPatch := fmt.Sprintf("v%d.%d.%d", v.Major, v.Minor, v.Patch+1)
+		if _, ok := majorMinorPatch[v.Major][v.Minor][v.Patch+1]; !ok && !seen[nextPatch] {
 			seen[nextPatch] = true
 			possible = append(possible, nextPatch)
 		}

internal/task/releasegopls_test.go

@@ -9,6 +9,7 @@ import (
 	"testing"
 
 	"github.com/google/go-cmp/cmp"
+	"golang.org/x/build/gerrit"
 	"golang.org/x/build/internal/workflow"
 )
 
@@ -73,7 +74,7 @@ func TestPossibleGoplsVersions(t *testing.T) {
 				Gerrit: gerrit,
 			}
 
-			got, err := tasks.possibleGoplsVersions(&workflow.TaskContext{Context: context.Background()})
+			got, err := tasks.possibleGoplsVersions(&workflow.TaskContext{Context: context.Background(), Logger: &testLogger{t, ""}})
 			if err != nil {
 				t.Fatalf("possibleGoplsVersions() should not return error, but return %v", err)
 			}
@@ -83,3 +84,90 @@ func TestPossibleGoplsVersions(t *testing.T) {
 		})
 	}
 }
+
+func TestCreateBranchIfMinor(t *testing.T) {
+	ctx := context.Background()
+	tests := []struct {
+		name           string
+		version        string
+		existingBranch string
+		wantErr        bool
+		wantBranch     string
+	}{
+		{
+			name:       "should create a release branch for a minor release",
+			version:    "v1.2.0",
+			wantErr:    false,
+			wantBranch: "gopls-release-branch.1.2",
+		},
+		{
+			name:           "should return nil if the release branch already exist for a minor release",
+			version:        "v1.2.0",
+			existingBranch: "gopls-release-branch.1.2",
+			wantErr:        false,
+		},
+		{
+			name:           "should not create a release branch for a patch release",
+			version:        "v1.2.4",
+			existingBranch: "gopls-release-branch.1.2",
+			wantErr:        false,
+			wantBranch:     "",
+		},
+		{
+			name:       "should throw error for patch release if release branch is missing",
+			version:    "v1.3.1",
+			wantErr:    true,
+			wantBranch: "",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			tools := NewFakeRepo(t, "tools")
+			_ = tools.Commit(map[string]string{
+				"go.mod": "module golang.org/x/tools\n",
+				"go.sum": "\n",
+			})
+			_ = tools.Commit(map[string]string{
+				"README.md": "THIS IS READ ME.",
+			})
+
+			gerritClient := NewFakeGerrit(t, tools)
+
+			masterHead, err := gerritClient.ReadBranchHead(ctx, "tools", "master")
+			if err != nil {
+				t.Fatalf("ReadBranchHead should be able to get revision of master branch's head: %v", err)
+			}
+
+			if tc.existingBranch != "" {
+				if _, err := gerritClient.CreateBranch(ctx, "tools", tc.existingBranch, gerrit.BranchInput{Revision: masterHead}); err != nil {
+					t.Fatalf("failed to create the branch %q: %v", tc.existingBranch, err)
+				}
+			}
+
+			tasks := &ReleaseGoplsTasks{
+				Gerrit: gerritClient,
+			}
+
+			semv, _ := parseSemver(tc.version)
+			err = tasks.createBranchIfMinor(&workflow.TaskContext{Context: ctx, Logger: &testLogger{t, ""}}, semv)
+
+			if tc.wantErr && err == nil {
+				t.Errorf("createBranchIfMinor() should return error but return nil")
+			} else if !tc.wantErr && err != nil {
+				t.Errorf("createBranchIfMinor() should return nil but return err: %v", err)
+			}
+
+			// Created branch should have same revision as master branch's HEAD.
+			if tc.wantBranch != "" {
+				gotRevision, err := gerritClient.ReadBranchHead(ctx, "tools", tc.wantBranch)
+				if err != nil {
+					t.Errorf("ReadBranchHead should be able to get revision of %s branch's head: %v", tc.wantBranch, err)
+				}
+				if masterHead != gotRevision {
+					t.Errorf("createBranchIfMinor() = %q, want %q", gotRevision, masterHead)
+				}
+			}
+		})
+	}
+}