test: Capitalize MUST and SHOULD directives
These directives in the API documentation have specific meanings.
Capitalizing makes this more apperant.
BUG=chromium:1063474
TEST=./generate.sh
Change-Id: Ie7577565a1600cf66fb2d52ec5f183ea4378a09b
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/infra/proto/+/2121573
Commit-Queue: Prathmesh Prabhu <pprabhu@chromium.org>
Tested-by: Prathmesh Prabhu <pprabhu@chromium.org>
Reviewed-by: Alex Zamorzaev <zamorzaev@chromium.org>
Reviewed-by: Jacob Kopczynski <jkop@chromium.org>
diff --git a/go/test/metadata/v1/metadata.pb.go b/go/test/metadata/v1/metadata.pb.go
index 4e33429..f8fd2a0 100644
--- a/go/test/metadata/v1/metadata.pb.go
+++ b/go/test/metadata/v1/metadata.pb.go
@@ -7,8 +7,8 @@
// This metadata is used for test execution requests, scheduling decisions and
// results analytics in various Test Lab Environments.
//
-// Metadata must be generated for all tests in supported Remote Test Drivers and
-// must be respected in all Test Lab Environments.
+// Metadata MUST be generated for all tests in supported Remote Test Drivers and
+// MUST be respected in all Test Lab Environments.
package metadata
@@ -34,7 +34,7 @@
// The test metadata specification.
//
-// Test metadata must be generated for each Remote Test Driver as one of the
+// Test metadata MUST be generated for each Remote Test Driver as one of the
// test artifacts generated from Chrome OS build system.
type Specification struct {
// A set of Remote Test Driver packages.
@@ -45,7 +45,7 @@
//
// Unlike tests, a RemoteTestDriver (identified by its name) may be specified
// multiple times, in a single Specification or across different Specification
- // instances. In that case, all fields except the list of tests must be
+ // instances. In that case, all fields except the list of tests MUST be
// identical across these RemoteTestDriver instances. The list of tests across
// these instances will be concatenated together.
RemoteTestDrivers []*RemoteTestDriver `protobuf:"bytes,1,rep,name=remote_test_drivers,json=remoteTestDrivers,proto3" json:"remote_test_drivers,omitempty"`
@@ -93,7 +93,7 @@
// Globally unique name for a Remote Test Driver package.
//
//
- // Must be a valid resource per https://aip.dev/122.
+ // MUST be a valid resource per https://aip.dev/122.
//
// Pattern: remoteTestDrivers/{remoteTestDriver}
//
@@ -106,16 +106,16 @@
// A container image containing all the required dependencies and other build
// artifacts required for test invocations.
//
- // Test Lab Environments should fail with an error indicating that the request
+ // Test Lab Environments SHOULD fail with an error indicating that the request
// was invalid if the image fails to be found for a test invocation.
Image *BuildArtifact `protobuf:"bytes,2,opt,name=image,proto3" json:"image,omitempty"`
// Command to invoke the Remote Test Driver inside `image`.
//
- // Remote Test Servers must run `command` as
+ // Remote Test Servers MUST run `command` as
// $ ${command} -input_json ${input_json}
// where ${command} and ${input_json} are absolute paths inside the container.
//
- // Remote Test Servers must populate `input_json` with a JSON encoded
+ // Remote Test Servers MUST populate `input_json` with a JSON encoded
// test.invocation.Request message.
Command string `protobuf:"bytes,3,opt,name=command,proto3" json:"command,omitempty"`
// Metadata for the smallest schedulable test units.
@@ -251,7 +251,7 @@
// this restriction.
//
// A single test platform request or Remote Test Driver invocation may contain
-// multiple instances of multiple Tests, but each instance of a Test must
+// multiple instances of multiple Tests, but each instance of a Test MUST
// correspond to exactly one reported result.
//
// See Also:
@@ -261,7 +261,7 @@
type Test struct {
// Globally unique name for this test.
//
- // Must be a valid resource per https://aip.dev/122.
+ // MUST be a valid resource per https://aip.dev/122.
//
// Pattern: remoteTestDrivers/{remoteTestDriver}/tests/{test}
// where {remoteTestDriver} is the Remote Test Driver package that contains
@@ -345,9 +345,9 @@
type Attribute struct {
// Opaque name for this attribute.
//
- // Value must be valid resource names per https://aip.dev/122.
+ // Value MUST be valid resource names per https://aip.dev/122.
//
- // Must not be interpreted by Test Lab Environments.
+ // MUST NOT be interpreted by Test Lab Environments.
Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
XXX_NoUnkeyedLiteral struct{} `json:"-"`
XXX_unrecognized []byte `json:"-"`
@@ -392,12 +392,12 @@
//
// Test Lab Environments may optionally support targeting test requests to
// Device Under Test based on DUTConditions. If this feature is supported, the
- // Test Lab Environment must interpret `expression` in the scope of the
+ // Test Lab Environment MUST interpret `expression` in the scope of the
// protobuf message DUTCondition.Scope as defined below.
//
// The full CEL spec can be found at https://github.com/google/cel-spec.
// This API only currently only supports a small sub-set of the CEL features,
- // as described here. Test Lab Environments should validate the expression and
+ // as described here. Test Lab Environments SHOULD validate the expression and
// reject use of unsupported features.
//
// TODO(crbug.com/1051689) Add reference to the metadata validator package.
@@ -428,9 +428,10 @@
//
// ### Evaluation context
//
- // A CEL expression must be evaluated in some context that provides the basic
- // bindings for name resolution. `expression` must be evaluated in an
- // evaluation context that contains
+ // In general, a CEL expression must be evaluated in some context that
+ // provides the basic bindings for name resolution.
+ //
+ // In this case, `expression` MUST be evaluated in a context that contains
//
// - A variable 'scope' of type DUTCondition.Scope. This variable contains the
// information about a particular Device Under Test being tested for
@@ -585,7 +586,7 @@
Authors []*Contact `protobuf:"bytes,1,rep,name=authors,proto3" json:"authors,omitempty"`
// Machine readable test-specific information.
//
- // Remote Test Drivers should include detailed information to aid analytics.
+ // Remote Test Drivers SHOULD include detailed information to aid analytics.
// For example, test authors may minimize code duplication by writing
// paramterized tests. Thus, multiple test metadata may refer to the
// same test implementation with different arguments. It is useful to include
@@ -598,7 +599,7 @@
// }
// }
//
- // This field must not be interpreted by the Test Lab Environments, but Remote
+ // This field MUST NOT be interpreted by the Test Lab Environments, but Remote
// Test Drivers can enrich analytics by using uniform stable schema for
// details across all their tests.
Details *_struct.Struct `protobuf:"bytes,2,opt,name=details,proto3" json:"details,omitempty"`
diff --git a/go/test/plan/v1/plan.pb.go b/go/test/plan/v1/plan.pb.go
index a74fca9..0f6a261 100644
--- a/go/test/plan/v1/plan.pb.go
+++ b/go/test/plan/v1/plan.pb.go
@@ -68,14 +68,14 @@
// A Plan fully specifies a Test Platform end-user's coverage needs.
//
-// Plans should associate platform software and Device Under Test condition
-// coverage rules with tests that exercise those components. Plans must be used
+// Plans SHOULD associate platform software and Device Under Test condition
+// coverage rules with tests that exercise those components. Plans MUST be used
// in the Test Platform request API. Other Test Lab Environments may use plans
// to ease interoperation with the Test Platform.
type Plan struct {
// A globally unique test plan name.
//
- // Must be valid resource name per https://aip.dev/122.
+ // MUST be valid resource name per https://aip.dev/122.
//
// Pattern: plans/{plan}
Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
@@ -130,29 +130,29 @@
type Unit struct {
// A globally unique test plan unit name.
//
- // Must be valid resource name per https://aip.dev/122.
+ // MUST be valid resource name per https://aip.dev/122.
//
// Pattern: plans/{plan}/units/{unit}
// where {plan} is the parent Plan of this Unit.
Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
// Selects tests to include in this test plan unit.
TestCondition *TestCondition `protobuf:"bytes,2,opt,name=test_condition,json=testCondition,proto3" json:"test_condition,omitempty"`
- // Selects the set of Devices Under Test that tests must be run on to satisfy
- // this test plan unit.
+ // Selects the set of Devices Under Test that satisfy the coverage
+ // requirements of this test plan unit.
DutCoverageCondition *DUTCoverageCondition `protobuf:"bytes,3,opt,name=dut_coverage_condition,json=dutCoverageCondition,proto3" json:"dut_coverage_condition,omitempty"`
// Chrome OS platform software covered by this test plan.
//
// Test Platform requests may optionally include a reference to platform
// software to be tested via the test plan. For such requests, Test Platform
- // must only execute test plan units that have non-trivial coverage of the
- // referenced platform software. Unrelated test plan units must be skipped.
+ // MUST only execute test plan units that have non-trivial coverage of the
+ // referenced platform software. Unrelated test plan units MUST be skipped.
//
// A typical example is presubmit testing: When testing a change to the
// network manager, it may be desirable to only run test plan units that
// are known to exercise the network manager.
//
- // For a test plan unit with no `code_coverage` specified, Test Platform must
- // assume coverage of all platform software (i.e., this test plan unit must
+ // For a test plan unit with no `code_coverage` specified, Test Platform MUST
+ // assume coverage of all platform software (i.e., this test plan unit MUST
// never be skipped for code coverage considerations).
CodeCoverage *CodeCoverage `protobuf:"bytes,4,opt,name=code_coverage,json=codeCoverage,proto3" json:"code_coverage,omitempty"`
XXX_NoUnkeyedLiteral struct{} `json:"-"`
@@ -218,7 +218,7 @@
// A Common Expression Language (CEL) expression to specify test conditions.
//
// The full CEL spec can be found at https://github.com/google/cel-spec.
- // Test Platform must interpret `expression` in the scope of
+ // Test Platform MUST interpret `expression` in the scope of
// `test.plan.TestCondition.Scope` defined below.
//
// ## Examples
@@ -236,13 +236,14 @@
//
// ## CEL support
//
- // All standard CEL syntax, macros and functions must be supported.
+ // All standard CEL syntax, macros and functions MUST be supported.
//
// ### Evaluation context
//
- // A CEL expression must be evaluated in some context that provides the basic
- // bindings for name resolution. `expression` must be evaluated in an
- // evaluation context that contains
+ // In general, a CEL expression must be evaluated in some context that
+ // provides the basic bindings for name resolution.
+ //
+ // In this case, `expression` MUST be evaluated in a context that contains
//
// - A variable 'scope' of type TestCondition.Scope. This variable contains
// the information about a particular Test being tested for
@@ -342,7 +343,7 @@
// A Common Expression Language (CEL) expression to specify set of DUTs that
// provide the necessary coverage.
//
- // Test Platform must interpret `expression` in the scope of the
+ // Test Platform MUST interpret `expression` in the scope of the
// protobuf message DUTCoverageCondition.Scope defined below. In summary, the
// expression allows selection of a set of Devices Under Test that provide the
// necessary coverage - Test Platform will determine a set of devices that
@@ -355,7 +356,7 @@
//
// The full CEL spec can be found at https://github.com/google/cel-spec.
// This API only supports a sub-set of the CEL features as described here.
- // Test Platform must validate the expression and reject use of unsupported
+ // Test Platform MUST validate the expression and reject use of unsupported
// features.
//
// TODO(crbug.com/1051689) Add reference to the metadata validator package.
@@ -392,7 +393,7 @@
// minimal set of devices to run the plan is best effort.
//
// Currently, only single-DUT constraints are supported by the Test Platform.
- // i.e., `expression` must be of the form:
+ // i.e., `expression` MUST be of the form:
// duts.all(DUT_SELECTOR) && size(duts) == 1
// where DUT_SELECTOR is an expression that does not refer to `duts`.
// This restriction will be lifted as this API matures.
@@ -410,9 +411,10 @@
//
// ### Evaluation context
//
- // A CEL expression must be evaluated in some context that provides the basic
- // bindings for name resolution. `expression` must be evaluated in an
- // evaluation context that contains
+ // In general, a CEL expression must be evaluated in some context that
+ // provides the basic bindings for name resolution.
+ //
+ // In this case, `expression` MUST be evaluated in a context that contains
//
// - A variable 'scope' of type DUTCoverageCondition.Scope. This variable
// contains the information about the set of Devices Under Test being
@@ -607,7 +609,7 @@
// A Common Expression Language (CEL) expression to specify code coverage.
//
// The full CEL spec can be found at https://github.com/google/cel-spec.
- // Test Platform must interpret `expression` in the scope of
+ // Test Platform MUST interpret `expression` in the scope of
// `test.plan.CodeCoverageCondition.Scope` defined below.
//
// ## Examples
@@ -626,13 +628,14 @@
//
// ## CEL support
//
- // All standard CEL syntax, macros and functions must be supported.
+ // All standard CEL syntax, macros and functions MUST be supported.
//
// ### Evaluation context
//
- // A CEL expression must be evaluated in some context that provides the basic
- // bindings for name resolution. `expression` must be evaluated in an
- // evaluation context that contains
+ // In general, a CEL expression must be evaluated in some context that
+ // provides the basic bindings for name resolution.
+ //
+ // In this case, `expression` MUST be evaluated in a context that contains
//
// - A variable 'scope' of type CodeCoverage.Scope. This variable contains
// the information about what platform software changes are intended to be
diff --git a/go/test/rtd/v1/invocation.pb.go b/go/test/rtd/v1/invocation.pb.go
index df86a38..6210c48 100644
--- a/go/test/rtd/v1/invocation.pb.go
+++ b/go/test/rtd/v1/invocation.pb.go
@@ -33,9 +33,9 @@
ProgressSinkClientConfig *ProgressSinkClientConfig `protobuf:"bytes,1,opt,name=progress_sink_client_config,json=progressSinkClientConfig,proto3" json:"progress_sink_client_config,omitempty"`
// Set of DUTs used for each of the requests in this invocation.
Duts []*DUT `protobuf:"bytes,2,rep,name=duts,proto3" json:"duts,omitempty"`
- // Smallest unit of an invocation request for which results must be reported.
+ // Smallest unit of an invocation request for which results MUST be reported.
//
- // An invocation must execute all requests serially in-order. This assumption
+ // An invocation MUST execute all requests serially in-order. This assumption
// is necessary for future support of test sequences in test plans.
Requests []*Request `protobuf:"bytes,3,rep,name=requests,proto3" json:"requests,omitempty"`
// Configuration information for using Test Lab Services to interact
@@ -110,9 +110,9 @@
HardwareFeatures *api.HardwareFeatures `protobuf:"bytes,3,opt,name=hardware_features,json=hardwareFeatures,proto3" json:"hardware_features,omitempty"`
// Name for the DUT for using Test Lab Services to interact with the
// device and its peripherals.
- // The RTD must pass this to certain Test Lab Service RPCs to specify
- // DUTs to act on.
- // See the tls.OpenDutPortRequest message for an example of where
+ //
+ // The RTD MUST pass this to Test Lab Service RPCs that act on a particular
+ // DUT. See the tls.OpenDutPortRequest message for an example of where
// this is used.
TlsDutName string `protobuf:"bytes,4,opt,name=tls_dut_name,json=tlsDutName,proto3" json:"tls_dut_name,omitempty"`
XXX_NoUnkeyedLiteral struct{} `json:"-"`
@@ -175,10 +175,10 @@
// Request for execution of a single test.metadata.Test
type Request struct {
- // name must be unique across all requests in this invocation.
+ // name MUST be unique across all requests in this invocation.
//
// Remote Test Drivers are recommended to use name as the opaque tag
- // required by the Test Lab Services API. Thus, name should be unique across
+ // required by the Test Lab Services API. Thus, name SHOULD be unique across
// all invocations to simplify analytics. UUIDs are recommended.
//
// See also:
@@ -248,12 +248,12 @@
type Request_Environment struct {
// Absolute path to a directory for writing arbitrary files.
//
- // This directory must be created by Remote Test Server prior to the Remote
+ // This directory MUST be created by Remote Test Server prior to the Remote
// Test Driver invocation.
//
- // * Remote Test Drivers should use
+ // * Remote Test Drivers SHOULD use
// test.invocation.ProgressClient.ReportLog() to report logs.
- // * Remote Test Drivers should use
+ // * Remote Test Drivers SHOULD use
// test.invocation.ProgressClient.ArchiveArtifact() to archive critical
// artifacts.
//
@@ -262,11 +262,11 @@
WorkDir string `protobuf:"bytes,1,opt,name=work_dir,json=workDir,proto3" json:"work_dir,omitempty"`
// Absolute path to a directory for writing temporary files.
//
- // This directory must be created by Remote Test Server prior to the Remote
+ // This directory MUST be created by Remote Test Server prior to the Remote
// Test Driver invocation.
//
- // Remote Test Drivers must use this directory for temporary files and must
- // not attempt to use defaults like /tmp or the TMP environment variable.
+ // Remote Test Drivers MUST use this directory for temporary files and MUST
+ // NOT attempt to use defaults like /tmp or the TMP environment variable.
//
// See also: Environment.work_dir
TempDir string `protobuf:"bytes,2,opt,name=temp_dir,json=tempDir,proto3" json:"temp_dir,omitempty"`
diff --git a/go/test/rtd/v1/progress.pb.go b/go/test/rtd/v1/progress.pb.go
index 74050ba..5699512 100644
--- a/go/test/rtd/v1/progress.pb.go
+++ b/go/test/rtd/v1/progress.pb.go
@@ -29,7 +29,7 @@
type Result_State int32
const (
- // No end state specified. Must not be used.
+ // No end state specified. MUST NOT be used.
Result_STATE_UNSPECIFIED Result_State = 0
// Test request succeeded. All was well.
Result_SUCCEEDED Result_State = 1
@@ -40,7 +40,7 @@
// Common reasons a test may be skipped:
//
// * A runtime check by the Remote Test Driver concluded that the test is
- // not applicable to the targeted device(s). The Remote Test Driver should
+ // not applicable to the targeted device(s). The Remote Test Driver SHOULD
// include detailed reasons in `errors`.
Result_SKIPPED Result_State = 3
)
@@ -71,9 +71,9 @@
type Result_Error_Source int32
const (
- // No Source specified. Should not be used.
+ // No Source specified. SHOULD NOT be used.
//
- // If source is unspecified, the Test Lab Environment should assume the
+ // If source is unspecified, the Test Lab Environment SHOULD assume the
// source to be the Remote Test Driver.
Result_Error_SOURCE_UNSPECIFIED Result_Error_Source = 0
// The test failed.
@@ -110,12 +110,12 @@
type Result_Error_Severity int32
const (
- // No Severity set. Should not be used.
+ // No Severity set. SHOULD NOT be used.
Result_Error_SEVERITY_UNSPECIFIED Result_Error_Severity = 0
- // Remote Test Server should validate that a Result contains a CRITICAL
+ // Remote Test Server SHOULD validate that a Result contains a CRITICAL
// message iff state == FAILED.
Result_Error_CRITICAL Result_Error_Severity = 1
- // Must not, by itself, lead to a FAILED Result.state.
+ // MUST NOT, by itself, lead to a FAILED Result.state.
Result_Error_WARNING Result_Error_Severity = 2
)
@@ -185,9 +185,9 @@
type Result struct {
// Final state of the test execution.
//
- // Error details must be available in `errors` if state != SUCCEEDED.
+ // Error details MUST be available in `errors` if state != SUCCEEDED.
State Result_State `protobuf:"varint,1,opt,name=state,proto3,enum=test.rtd.v1.Result_State" json:"state,omitempty"`
- // errors must be set if state != SUCCEEDED.
+ // errors MUST be set if state != SUCCEEDED.
//
// errors may be provided even if state == SUCCEEDED. Remote Test Drivers are
// encouraged to provide multiple observed errors in Result to aid end-user
@@ -244,10 +244,10 @@
Severity Result_Error_Severity `protobuf:"varint,2,opt,name=severity,proto3,enum=test.rtd.v1.Result_Error_Severity" json:"severity,omitempty"`
// Machine parseable details about the error.
//
- // Test Lab Environments and Remote Test Servers must not interpret the
+ // Test Lab Environments and Remote Test Servers MUST NOT interpret the
// details.
//
- // Remote Test Drivers should use uniform stable schema for `details` to
+ // Remote Test Drivers SHOULD use uniform stable schema for `details` to
// enable robust analytics.
Details *_struct.Struct `protobuf:"bytes,3,opt,name=details,proto3" json:"details,omitempty"`
XXX_NoUnkeyedLiteral struct{} `json:"-"`
@@ -352,7 +352,7 @@
}
type ReportResultResponse struct {
- // If set, the invocation should immediately terminate, skipping remaining
+ // If set, the invocation SHOULD immediately terminate, skipping remaining
// requests.
Terminate bool `protobuf:"varint,1,opt,name=terminate,proto3" json:"terminate,omitempty"`
XXX_NoUnkeyedLiteral struct{} `json:"-"`
@@ -395,8 +395,8 @@
type ReportLogRequest struct {
// Name of the log sink.
//
- // name may be interpreted as a local file path or part of a URL. name must be
- // a valid resource name per https://aip.dev/122 and must be a valid POSIX
+ // name may be interpreted as a local file path or part of a URL. name MUST be
+ // a valid resource name per https://aip.dev/122 and MUST be a valid POSIX
// file path.
Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
// The request to report logs for, identified by the
@@ -489,11 +489,11 @@
type ArchiveArtifactRequest struct {
// Name for the archived artifact.
//
- // name may be interpreted as a local file path or part of a URL. name must be
- // a valid resource name per https://aip.dev/122 and must be a valid POSIX
+ // name may be interpreted as a local file path or part of a URL. name MUST be
+ // a valid resource name per https://aip.dev/122 and MUST be a valid POSIX
// file path.
//
- // name must be unique across all artifacts archived from a single invocation
+ // name MUST be unique across all artifacts archived from a single invocation
// request.
Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
// The request to archive artifacts for, identified by the
@@ -659,12 +659,12 @@
//
// For semantics around ctx use and closing/ending streaming RPCs, please refer to https://godoc.org/google.golang.org/grpc#ClientConn.NewStream.
type ProgressSinkClient interface {
- // A Remote Test Driver invocation must call ReportResult exactly once per
+ // A Remote Test Driver invocation MUST call ReportResult exactly once per
// request.
ReportResult(ctx context.Context, in *ReportResultRequest, opts ...grpc.CallOption) (*ReportResultResponse, error)
// A log stream from the Remote Test Driver invocation.
//
- // Each call to this method must stream logs for a single invocation request
+ // Each call to this method MUST stream logs for a single invocation request
// and log file. Data for the same file may be split over multiple ReportLog
// calls. Data received from concurrent methods calls for the same log file
// may be interleved arbitrarily.
@@ -672,11 +672,11 @@
// Archive test artifacts to non-ephemeral storage.
//
// Different Test Lab Environments may use very different non-ephemeral
- // storage technologies. Remote Test Servers must archive the artifacts to
+ // storage technologies. Remote Test Servers MUST archive the artifacts to
// final storage synchronously and return an error if the archival fails.
//
- // Note: Remote Test Drivers should use ReportLog() to report logs.
- // ArchiveArtifact() should be used to report structured or binary data only.
+ // Note: Remote Test Drivers SHOULD use ReportLog() to report logs.
+ // ArchiveArtifact() SHOULD be used to report structured or binary data only.
//
// Remote Test Server may limit the size of artifacts that may be offloaded
// per request and may fail further requests with RESOURCE_EXHAUSTED.
@@ -745,12 +745,12 @@
// ProgressSinkServer is the server API for ProgressSink service.
type ProgressSinkServer interface {
- // A Remote Test Driver invocation must call ReportResult exactly once per
+ // A Remote Test Driver invocation MUST call ReportResult exactly once per
// request.
ReportResult(context.Context, *ReportResultRequest) (*ReportResultResponse, error)
// A log stream from the Remote Test Driver invocation.
//
- // Each call to this method must stream logs for a single invocation request
+ // Each call to this method MUST stream logs for a single invocation request
// and log file. Data for the same file may be split over multiple ReportLog
// calls. Data received from concurrent methods calls for the same log file
// may be interleved arbitrarily.
@@ -758,11 +758,11 @@
// Archive test artifacts to non-ephemeral storage.
//
// Different Test Lab Environments may use very different non-ephemeral
- // storage technologies. Remote Test Servers must archive the artifacts to
+ // storage technologies. Remote Test Servers MUST archive the artifacts to
// final storage synchronously and return an error if the archival fails.
//
- // Note: Remote Test Drivers should use ReportLog() to report logs.
- // ArchiveArtifact() should be used to report structured or binary data only.
+ // Note: Remote Test Drivers SHOULD use ReportLog() to report logs.
+ // ArchiveArtifact() SHOULD be used to report structured or binary data only.
//
// Remote Test Server may limit the size of artifacts that may be offloaded
// per request and may fail further requests with RESOURCE_EXHAUSTED.
diff --git a/src/test/metadata/v1/metadata.proto b/src/test/metadata/v1/metadata.proto
index 87af7c5..b6422fa 100644
--- a/src/test/metadata/v1/metadata.proto
+++ b/src/test/metadata/v1/metadata.proto
@@ -10,8 +10,8 @@
// This metadata is used for test execution requests, scheduling decisions and
// results analytics in various Test Lab Environments.
//
-// Metadata must be generated for all tests in supported Remote Test Drivers and
-// must be respected in all Test Lab Environments.
+// Metadata MUST be generated for all tests in supported Remote Test Drivers and
+// MUST be respected in all Test Lab Environments.
package test.metadata.v1;
option go_package = "go.chromium.org/chromiumos/infra/proto/go/test/metadata/v1;metadata";
@@ -26,7 +26,7 @@
// The test metadata specification.
//
-// Test metadata must be generated for each Remote Test Driver as one of the
+// Test metadata MUST be generated for each Remote Test Driver as one of the
// test artifacts generated from Chrome OS build system.
message Specification {
// A set of Remote Test Driver packages.
@@ -37,7 +37,7 @@
//
// Unlike tests, a RemoteTestDriver (identified by its name) may be specified
// multiple times, in a single Specification or across different Specification
- // instances. In that case, all fields except the list of tests must be
+ // instances. In that case, all fields except the list of tests MUST be
// identical across these RemoteTestDriver instances. The list of tests across
// these instances will be concatenated together.
repeated RemoteTestDriver remote_test_drivers = 1;
@@ -50,7 +50,7 @@
// Globally unique name for a Remote Test Driver package.
//
//
- // Must be a valid resource per https://aip.dev/122.
+ // MUST be a valid resource per https://aip.dev/122.
//
// Pattern: remoteTestDrivers/{remoteTestDriver}
//
@@ -64,17 +64,17 @@
// A container image containing all the required dependencies and other build
// artifacts required for test invocations.
//
- // Test Lab Environments should fail with an error indicating that the request
+ // Test Lab Environments SHOULD fail with an error indicating that the request
// was invalid if the image fails to be found for a test invocation.
BuildArtifact image = 2;
// Command to invoke the Remote Test Driver inside `image`.
//
- // Remote Test Servers must run `command` as
+ // Remote Test Servers MUST run `command` as
// $ ${command} -input_json ${input_json}
// where ${command} and ${input_json} are absolute paths inside the container.
//
- // Remote Test Servers must populate `input_json` with a JSON encoded
+ // Remote Test Servers MUST populate `input_json` with a JSON encoded
// test.invocation.Request message.
string command = 3;
@@ -120,7 +120,7 @@
// this restriction.
//
// A single test platform request or Remote Test Driver invocation may contain
-// multiple instances of multiple Tests, but each instance of a Test must
+// multiple instances of multiple Tests, but each instance of a Test MUST
// correspond to exactly one reported result.
//
// See Also:
@@ -130,7 +130,7 @@
message Test {
// Globally unique name for this test.
//
- // Must be a valid resource per https://aip.dev/122.
+ // MUST be a valid resource per https://aip.dev/122.
//
// Pattern: remoteTestDrivers/{remoteTestDriver}/tests/{test}
// where {remoteTestDriver} is the Remote Test Driver package that contains
@@ -161,9 +161,9 @@
message Attribute {
// Opaque name for this attribute.
//
- // Value must be valid resource names per https://aip.dev/122.
+ // Value MUST be valid resource names per https://aip.dev/122.
//
- // Must not be interpreted by Test Lab Environments.
+ // MUST NOT be interpreted by Test Lab Environments.
string name = 1;
}
@@ -173,12 +173,12 @@
//
// Test Lab Environments may optionally support targeting test requests to
// Device Under Test based on DUTConditions. If this feature is supported, the
- // Test Lab Environment must interpret `expression` in the scope of the
+ // Test Lab Environment MUST interpret `expression` in the scope of the
// protobuf message DUTCondition.Scope as defined below.
//
// The full CEL spec can be found at https://github.com/google/cel-spec.
// This API only currently only supports a small sub-set of the CEL features,
- // as described here. Test Lab Environments should validate the expression and
+ // as described here. Test Lab Environments SHOULD validate the expression and
// reject use of unsupported features.
//
// TODO(crbug.com/1051689) Add reference to the metadata validator package.
@@ -209,9 +209,10 @@
//
// ### Evaluation context
//
- // A CEL expression must be evaluated in some context that provides the basic
- // bindings for name resolution. `expression` must be evaluated in an
- // evaluation context that contains
+ // In general, a CEL expression must be evaluated in some context that
+ // provides the basic bindings for name resolution.
+ //
+ // In this case, `expression` MUST be evaluated in a context that contains
//
// - A variable 'scope' of type DUTCondition.Scope. This variable contains the
// information about a particular Device Under Test being tested for
@@ -283,7 +284,7 @@
// Machine readable test-specific information.
//
- // Remote Test Drivers should include detailed information to aid analytics.
+ // Remote Test Drivers SHOULD include detailed information to aid analytics.
// For example, test authors may minimize code duplication by writing
// paramterized tests. Thus, multiple test metadata may refer to the
// same test implementation with different arguments. It is useful to include
@@ -296,7 +297,7 @@
// }
// }
//
- // This field must not be interpreted by the Test Lab Environments, but Remote
+ // This field MUST NOT be interpreted by the Test Lab Environments, but Remote
// Test Drivers can enrich analytics by using uniform stable schema for
// details across all their tests.
google.protobuf.Struct details = 2;
diff --git a/src/test/plan/v1/plan.proto b/src/test/plan/v1/plan.proto
index fd92674..c79138a 100644
--- a/src/test/plan/v1/plan.proto
+++ b/src/test/plan/v1/plan.proto
@@ -25,14 +25,14 @@
// A Plan fully specifies a Test Platform end-user's coverage needs.
//
-// Plans should associate platform software and Device Under Test condition
-// coverage rules with tests that exercise those components. Plans must be used
+// Plans SHOULD associate platform software and Device Under Test condition
+// coverage rules with tests that exercise those components. Plans MUST be used
// in the Test Platform request API. Other Test Lab Environments may use plans
// to ease interoperation with the Test Platform.
message Plan {
// A globally unique test plan name.
//
- // Must be valid resource name per https://aip.dev/122.
+ // MUST be valid resource name per https://aip.dev/122.
//
// Pattern: plans/{plan}
string name = 1;
@@ -46,7 +46,7 @@
message Unit {
// A globally unique test plan unit name.
//
- // Must be valid resource name per https://aip.dev/122.
+ // MUST be valid resource name per https://aip.dev/122.
//
// Pattern: plans/{plan}/units/{unit}
// where {plan} is the parent Plan of this Unit.
@@ -55,23 +55,23 @@
// Selects tests to include in this test plan unit.
TestCondition test_condition = 2;
- // Selects the set of Devices Under Test that tests must be run on to satisfy
- // this test plan unit.
+ // Selects the set of Devices Under Test that satisfy the coverage
+ // requirements of this test plan unit.
DUTCoverageCondition dut_coverage_condition = 3;
// Chrome OS platform software covered by this test plan.
//
// Test Platform requests may optionally include a reference to platform
// software to be tested via the test plan. For such requests, Test Platform
- // must only execute test plan units that have non-trivial coverage of the
- // referenced platform software. Unrelated test plan units must be skipped.
+ // MUST only execute test plan units that have non-trivial coverage of the
+ // referenced platform software. Unrelated test plan units MUST be skipped.
//
// A typical example is presubmit testing: When testing a change to the
// network manager, it may be desirable to only run test plan units that
// are known to exercise the network manager.
//
- // For a test plan unit with no `code_coverage` specified, Test Platform must
- // assume coverage of all platform software (i.e., this test plan unit must
+ // For a test plan unit with no `code_coverage` specified, Test Platform MUST
+ // assume coverage of all platform software (i.e., this test plan unit MUST
// never be skipped for code coverage considerations).
CodeCoverage code_coverage = 4;
}
@@ -81,7 +81,7 @@
// A Common Expression Language (CEL) expression to specify test conditions.
//
// The full CEL spec can be found at https://github.com/google/cel-spec.
- // Test Platform must interpret `expression` in the scope of
+ // Test Platform MUST interpret `expression` in the scope of
// `test.plan.TestCondition.Scope` defined below.
//
// ## Examples
@@ -99,13 +99,14 @@
//
// ## CEL support
//
- // All standard CEL syntax, macros and functions must be supported.
+ // All standard CEL syntax, macros and functions MUST be supported.
//
// ### Evaluation context
//
- // A CEL expression must be evaluated in some context that provides the basic
- // bindings for name resolution. `expression` must be evaluated in an
- // evaluation context that contains
+ // In general, a CEL expression must be evaluated in some context that
+ // provides the basic bindings for name resolution.
+ //
+ // In this case, `expression` MUST be evaluated in a context that contains
//
// - A variable 'scope' of type TestCondition.Scope. This variable contains
// the information about a particular Test being tested for
@@ -129,7 +130,7 @@
// A Common Expression Language (CEL) expression to specify set of DUTs that
// provide the necessary coverage.
//
- // Test Platform must interpret `expression` in the scope of the
+ // Test Platform MUST interpret `expression` in the scope of the
// protobuf message DUTCoverageCondition.Scope defined below. In summary, the
// expression allows selection of a set of Devices Under Test that provide the
// necessary coverage - Test Platform will determine a set of devices that
@@ -142,7 +143,7 @@
//
// The full CEL spec can be found at https://github.com/google/cel-spec.
// This API only supports a sub-set of the CEL features as described here.
- // Test Platform must validate the expression and reject use of unsupported
+ // Test Platform MUST validate the expression and reject use of unsupported
// features.
//
// TODO(crbug.com/1051689) Add reference to the metadata validator package.
@@ -179,7 +180,7 @@
// minimal set of devices to run the plan is best effort.
//
// Currently, only single-DUT constraints are supported by the Test Platform.
- // i.e., `expression` must be of the form:
+ // i.e., `expression` MUST be of the form:
// duts.all(DUT_SELECTOR) && size(duts) == 1
// where DUT_SELECTOR is an expression that does not refer to `duts`.
// This restriction will be lifted as this API matures.
@@ -197,9 +198,10 @@
//
// ### Evaluation context
//
- // A CEL expression must be evaluated in some context that provides the basic
- // bindings for name resolution. `expression` must be evaluated in an
- // evaluation context that contains
+ // In general, a CEL expression must be evaluated in some context that
+ // provides the basic bindings for name resolution.
+ //
+ // In this case, `expression` MUST be evaluated in a context that contains
//
// - A variable 'scope' of type DUTCoverageCondition.Scope. This variable
// contains the information about the set of Devices Under Test being
@@ -275,7 +277,7 @@
// A Common Expression Language (CEL) expression to specify code coverage.
//
// The full CEL spec can be found at https://github.com/google/cel-spec.
- // Test Platform must interpret `expression` in the scope of
+ // Test Platform MUST interpret `expression` in the scope of
// `test.plan.CodeCoverageCondition.Scope` defined below.
//
// ## Examples
@@ -294,13 +296,14 @@
//
// ## CEL support
//
- // All standard CEL syntax, macros and functions must be supported.
+ // All standard CEL syntax, macros and functions MUST be supported.
//
// ### Evaluation context
//
- // A CEL expression must be evaluated in some context that provides the basic
- // bindings for name resolution. `expression` must be evaluated in an
- // evaluation context that contains
+ // In general, a CEL expression must be evaluated in some context that
+ // provides the basic bindings for name resolution.
+ //
+ // In this case, `expression` MUST be evaluated in a context that contains
//
// - A variable 'scope' of type CodeCoverage.Scope. This variable contains
// the information about what platform software changes are intended to be
diff --git a/src/test/rtd/v1/invocation.proto b/src/test/rtd/v1/invocation.proto
index 96281ff..88b8006 100644
--- a/src/test/rtd/v1/invocation.proto
+++ b/src/test/rtd/v1/invocation.proto
@@ -28,9 +28,9 @@
// Set of DUTs used for each of the requests in this invocation.
repeated DUT duts = 2;
- // Smallest unit of an invocation request for which results must be reported.
+ // Smallest unit of an invocation request for which results MUST be reported.
//
- // An invocation must execute all requests serially in-order. This assumption
+ // An invocation MUST execute all requests serially in-order. This assumption
// is necessary for future support of test sequences in test plans.
repeated Request requests = 3;
@@ -52,19 +52,19 @@
// Name for the DUT for using Test Lab Services to interact with the
// device and its peripherals.
- // The RTD must pass this to certain Test Lab Service RPCs to specify
- // DUTs to act on.
- // See the tls.OpenDutPortRequest message for an example of where
+ //
+ // The RTD MUST pass this to Test Lab Service RPCs that act on a particular
+ // DUT. See the tls.OpenDutPortRequest message for an example of where
// this is used.
string tls_dut_name = 4;
}
// Request for execution of a single test.metadata.Test
message Request {
- // name must be unique across all requests in this invocation.
+ // name MUST be unique across all requests in this invocation.
//
// Remote Test Drivers are recommended to use name as the opaque tag
- // required by the Test Lab Services API. Thus, name should be unique across
+ // required by the Test Lab Services API. Thus, name SHOULD be unique across
// all invocations to simplify analytics. UUIDs are recommended.
//
// See also:
@@ -82,12 +82,12 @@
message Environment {
// Absolute path to a directory for writing arbitrary files.
//
- // This directory must be created by Remote Test Server prior to the Remote
+ // This directory MUST be created by Remote Test Server prior to the Remote
// Test Driver invocation.
//
- // * Remote Test Drivers should use
+ // * Remote Test Drivers SHOULD use
// test.invocation.ProgressClient.ReportLog() to report logs.
- // * Remote Test Drivers should use
+ // * Remote Test Drivers SHOULD use
// test.invocation.ProgressClient.ArchiveArtifact() to archive critical
// artifacts.
//
@@ -97,11 +97,11 @@
// Absolute path to a directory for writing temporary files.
//
- // This directory must be created by Remote Test Server prior to the Remote
+ // This directory MUST be created by Remote Test Server prior to the Remote
// Test Driver invocation.
//
- // Remote Test Drivers must use this directory for temporary files and must
- // not attempt to use defaults like /tmp or the TMP environment variable.
+ // Remote Test Drivers MUST use this directory for temporary files and MUST
+ // NOT attempt to use defaults like /tmp or the TMP environment variable.
//
// See also: Environment.work_dir
string temp_dir = 2;
diff --git a/src/test/rtd/v1/progress.proto b/src/test/rtd/v1/progress.proto
index b83acbc..ffa61d7 100644
--- a/src/test/rtd/v1/progress.proto
+++ b/src/test/rtd/v1/progress.proto
@@ -21,23 +21,23 @@
// Remote Test Driver invocation.
//
// A simple implementation of Remote Test Driver may report progress at the
-// end of the invocation for all requests together. Real implementations should
+// end of the invocation for all requests together. Real implementations SHOULD
// report incremental progress during the invocation.
//
-// A progress sink service instance is tied to a single Invocation. There must
+// A progress sink service instance is tied to a single Invocation. There MUST
// always be a single Remote Test Driver invocation inside a Remote Test Server.
// If a Test Lab Environment desires to share a ProgressSink instance across
// various Remote Test Servers, a way to dinstinguish the different Remote Test
// Driver clients must be determined, which is not supported directly by the
// following API.
service ProgressSink {
- // A Remote Test Driver invocation must call ReportResult exactly once per
+ // A Remote Test Driver invocation MUST call ReportResult exactly once per
// request.
rpc ReportResult(ReportResultRequest) returns (ReportResultResponse);
// A log stream from the Remote Test Driver invocation.
//
- // Each call to this method must stream logs for a single invocation request
+ // Each call to this method MUST stream logs for a single invocation request
// and log file. Data for the same file may be split over multiple ReportLog
// calls. Data received from concurrent methods calls for the same log file
// may be interleved arbitrarily.
@@ -46,11 +46,11 @@
// Archive test artifacts to non-ephemeral storage.
//
// Different Test Lab Environments may use very different non-ephemeral
- // storage technologies. Remote Test Servers must archive the artifacts to
+ // storage technologies. Remote Test Servers MUST archive the artifacts to
// final storage synchronously and return an error if the archival fails.
//
- // Note: Remote Test Drivers should use ReportLog() to report logs.
- // ArchiveArtifact() should be used to report structured or binary data only.
+ // Note: Remote Test Drivers SHOULD use ReportLog() to report logs.
+ // ArchiveArtifact() SHOULD be used to report structured or binary data only.
//
// Remote Test Server may limit the size of artifacts that may be offloaded
// per request and may fail further requests with RESOURCE_EXHAUSTED.
@@ -61,7 +61,7 @@
message Result {
// Enum entries *may* be added to this enum in the future.
enum State {
- // No end state specified. Must not be used.
+ // No end state specified. MUST NOT be used.
STATE_UNSPECIFIED = 0;
// Test request succeeded. All was well.
SUCCEEDED = 1;
@@ -72,21 +72,21 @@
// Common reasons a test may be skipped:
//
// * A runtime check by the Remote Test Driver concluded that the test is
- // not applicable to the targeted device(s). The Remote Test Driver should
+ // not applicable to the targeted device(s). The Remote Test Driver SHOULD
// include detailed reasons in `errors`.
SKIPPED = 3;
}
// Final state of the test execution.
//
- // Error details must be available in `errors` if state != SUCCEEDED.
+ // Error details MUST be available in `errors` if state != SUCCEEDED.
State state = 1;
message Error {
// Enum entries *may* be added in the future.
enum Source {
- // No Source specified. Should not be used.
+ // No Source specified. SHOULD NOT be used.
//
- // If source is unspecified, the Test Lab Environment should assume the
+ // If source is unspecified, the Test Lab Environment SHOULD assume the
// source to be the Remote Test Driver.
SOURCE_UNSPECIFIED = 0;
// The test failed.
@@ -102,12 +102,12 @@
// Enum entries *may* be added in the future.
enum Severity {
- // No Severity set. Should not be used.
+ // No Severity set. SHOULD NOT be used.
SEVERITY_UNSPECIFIED = 0;
- // Remote Test Server should validate that a Result contains a CRITICAL
+ // Remote Test Server SHOULD validate that a Result contains a CRITICAL
// message iff state == FAILED.
CRITICAL = 1;
- // Must not, by itself, lead to a FAILED Result.state.
+ // MUST NOT, by itself, lead to a FAILED Result.state.
WARNING = 2;
}
@@ -116,15 +116,15 @@
// Machine parseable details about the error.
//
- // Test Lab Environments and Remote Test Servers must not interpret the
+ // Test Lab Environments and Remote Test Servers MUST NOT interpret the
// details.
//
- // Remote Test Drivers should use uniform stable schema for `details` to
+ // Remote Test Drivers SHOULD use uniform stable schema for `details` to
// enable robust analytics.
google.protobuf.Struct details = 3;
}
- // errors must be set if state != SUCCEEDED.
+ // errors MUST be set if state != SUCCEEDED.
//
// errors may be provided even if state == SUCCEEDED. Remote Test Drivers are
// encouraged to provide multiple observed errors in Result to aid end-user
@@ -142,7 +142,7 @@
}
message ReportResultResponse {
- // If set, the invocation should immediately terminate, skipping remaining
+ // If set, the invocation SHOULD immediately terminate, skipping remaining
// requests.
bool terminate = 1;
}
@@ -150,8 +150,8 @@
message ReportLogRequest {
// Name of the log sink.
//
- // name may be interpreted as a local file path or part of a URL. name must be
- // a valid resource name per https://aip.dev/122 and must be a valid POSIX
+ // name may be interpreted as a local file path or part of a URL. name MUST be
+ // a valid resource name per https://aip.dev/122 and MUST be a valid POSIX
// file path.
string name = 1;
@@ -168,11 +168,11 @@
message ArchiveArtifactRequest {
// Name for the archived artifact.
//
- // name may be interpreted as a local file path or part of a URL. name must be
- // a valid resource name per https://aip.dev/122 and must be a valid POSIX
+ // name may be interpreted as a local file path or part of a URL. name MUST be
+ // a valid resource name per https://aip.dev/122 and MUST be a valid POSIX
// file path.
//
- // name must be unique across all artifacts archived from a single invocation
+ // name MUST be unique across all artifacts archived from a single invocation
// request.
string name = 1;
