maintner/maintnerd: improve API documentation
Rearrange the maintner API documentation, and reflect the guarantee of
at least two Go releases on success.
Updates golang/go#32606
Change-Id: I90d5017f280254cc6482e747ffc1534f8a51bc20
Reviewed-on: https://go-review.googlesource.com/c/build/+/182981
Run-TryBot: Alexander Rakoczy <alex@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
diff --git a/maintner/maintnerd/apipb/api.pb.go b/maintner/maintnerd/apipb/api.pb.go
index 7767d65..0ee86ad 100644
--- a/maintner/maintnerd/apipb/api.pb.go
+++ b/maintner/maintnerd/apipb/api.pb.go
@@ -273,8 +273,6 @@
return 0
}
-// By default, ListGoReleases returns only the latest patches
-// of releases that are considered supported per policy.
type ListGoReleasesRequest struct {
}
@@ -284,7 +282,6 @@
func (*ListGoReleasesRequest) Descriptor() ([]byte, []int) { return fileDescriptor0, []int{8} }
type ListGoReleasesResponse struct {
- // Releases are Go releases, sorted by version with latest first.
Releases []*GoRelease `protobuf:"bytes,1,rep,name=releases" json:"releases,omitempty"`
}
@@ -397,9 +394,16 @@
GetRef(ctx context.Context, in *GetRefRequest, opts ...grpc.CallOption) (*GetRefResponse, error)
// GoFindTryWork finds trybot work for the coordinator to build & test.
GoFindTryWork(ctx context.Context, in *GoFindTryWorkRequest, opts ...grpc.CallOption) (*GoFindTryWorkResponse, error)
- // ListGoReleases lists Go releases. A release is considered to exist for
- // each git tag named "goX", "goX.Y", or "goX.Y.Z", as long as it has a
- // corresponding "release-branch.goX" or "release-branch.goX.Y" release branch.
+ // ListGoReleases lists Go releases sorted by version with latest first.
+ //
+ // A release is considered to exist for each git tag named "goX", "goX.Y", or
+ // "goX.Y.Z", as long as it has a corresponding "release-branch.goX" or
+ // "release-branch.goX.Y" release branch.
+ //
+ // ListGoReleases returns only the latest patch versions of releases which
+ // are considered supported per policy. For example, Go 1.12.6 and 1.11.11.
+ // The response is guaranteed to have two versions, otherwise an error
+ // is returned.
ListGoReleases(ctx context.Context, in *ListGoReleasesRequest, opts ...grpc.CallOption) (*ListGoReleasesResponse, error)
}
@@ -457,9 +461,16 @@
GetRef(context.Context, *GetRefRequest) (*GetRefResponse, error)
// GoFindTryWork finds trybot work for the coordinator to build & test.
GoFindTryWork(context.Context, *GoFindTryWorkRequest) (*GoFindTryWorkResponse, error)
- // ListGoReleases lists Go releases. A release is considered to exist for
- // each git tag named "goX", "goX.Y", or "goX.Y.Z", as long as it has a
- // corresponding "release-branch.goX" or "release-branch.goX.Y" release branch.
+ // ListGoReleases lists Go releases sorted by version with latest first.
+ //
+ // A release is considered to exist for each git tag named "goX", "goX.Y", or
+ // "goX.Y.Z", as long as it has a corresponding "release-branch.goX" or
+ // "release-branch.goX.Y" release branch.
+ //
+ // ListGoReleases returns only the latest patch versions of releases which
+ // are considered supported per policy. For example, Go 1.12.6 and 1.11.11.
+ // The response is guaranteed to have two versions, otherwise an error
+ // is returned.
ListGoReleases(context.Context, *ListGoReleasesRequest) (*ListGoReleasesResponse, error)
}
diff --git a/maintner/maintnerd/apipb/api.proto b/maintner/maintnerd/apipb/api.proto
index dded094..756d5fa 100644
--- a/maintner/maintnerd/apipb/api.proto
+++ b/maintner/maintnerd/apipb/api.proto
@@ -72,12 +72,9 @@
int32 minor = 2;
}
-// By default, ListGoReleases returns only the latest patches
-// of releases that are considered supported per policy.
message ListGoReleasesRequest {}
message ListGoReleasesResponse {
- // Releases are Go releases, sorted by version with latest first.
repeated GoRelease releases = 1;
}
@@ -106,8 +103,15 @@
// GoFindTryWork finds trybot work for the coordinator to build & test.
rpc GoFindTryWork(GoFindTryWorkRequest) returns (GoFindTryWorkResponse);
- // ListGoReleases lists Go releases. A release is considered to exist for
- // each git tag named "goX", "goX.Y", or "goX.Y.Z", as long as it has a
- // corresponding "release-branch.goX" or "release-branch.goX.Y" release branch.
+ // ListGoReleases lists Go releases sorted by version with latest first.
+ //
+ // A release is considered to exist for each git tag named "goX", "goX.Y", or
+ // "goX.Y.Z", as long as it has a corresponding "release-branch.goX" or
+ // "release-branch.goX.Y" release branch.
+ //
+ // ListGoReleases returns only the latest patch versions of releases which
+ // are considered supported per policy. For example, Go 1.12.6 and 1.11.11.
+ // The response is guaranteed to have two versions, otherwise an error
+ // is returned.
rpc ListGoReleases(ListGoReleasesRequest) returns (ListGoReleasesResponse);
}
