1/*
2 * Copyright (C) 2024 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17syntax = "proto3";
18
19package luci.resultdb.v1;
20
21import "google/protobuf/timestamp.proto";
22
23option go_package = "go.chromium.org/luci/resultdb/proto/v1;resultpb";
24option java_package = "com.android.resultdb.proto";
25option java_multiple_files = true;
26
27// A key-value map describing one variant of a test case.
28//
29// The same test case can be executed in different ways, for example on
30// different OS, GPUs, with different compile options or runtime flags.
31// A variant definition captures one variant.
32// A test case with a specific variant definition is called test variant.
33//
34// Guidelines for variant definition design:
35// - This rule guides what keys MUST be present in the definition.
36//   A single expected result of a given test variant is enough to consider it
37//   passing (potentially flakily). If it is important to differentiate across
38//   a certain dimension (e.g. whether web tests are executed with or without
39//   site per process isolation), then there MUST be a key that captures the
40//   dimension (e.g. a name from test_suites.pyl).
41//   Otherwise, a pass in one variant will hide a failure of another one.
42//
43// - This rule guides what keys MUST NOT be present in the definition.
44//   A change in the key-value set essentially resets the test result history.
45//   For example, if GN args are among variant key-value pairs, then adding a
46//   new GN arg changes the identity of the test variant and resets its history.
47//
48// In Chromium, variant keys are:
49// - bucket: the LUCI bucket, e.g. "ci"
50// - builder: the LUCI builder, e.g. "linux-rel"
51// - test_suite: a name from
52//   https://cs.chromium.org/chromium/src/testing/buildbot/test_suites.pyl
53message Variant {
54  // The definition of the variant.
55  // Key and values must be valid StringPair keys and values, see their
56  // constraints.
57  map<string, string> def = 1;
58}
59
60// A string key-value pair. Typically used for tagging, see Invocation.tags
61message StringPair {
62  // Regex: ^[a-z][a-z0-9_]*(/[a-z][a-z0-9_]*)*$
63  // Max length: 64.
64  string key = 1;
65
66  // Max length: 256.
67  string value = 2;
68}
69
70// GitilesCommit specifies the position of the gitiles commit an invocation
71// ran against, in a repository's commit log. More specifically, a ref's commit
72// log.
73//
74// It also specifies the host/project/ref combination that the commit
75// exists in, to provide context.
76message GitilesCommit {
77  // The identity of the gitiles host, e.g. "chromium.googlesource.com".
78  // Mandatory.
79  string host = 1;
80
81  // Repository name on the host, e.g. "chromium/src". Mandatory.
82  string project = 2;
83
84  // Commit ref, e.g. "refs/heads/main" from which the commit was fetched.
85  // Not the branch name, use "refs/heads/branch"
86  // Mandatory.
87  string ref = 3;
88
89  // Commit HEX SHA1. All lowercase. Mandatory.
90  string commit_hash = 4;
91
92  // Defines a total order of commits on the ref.
93  // A positive, monotonically increasing integer. The recommended
94  // way of obtaining this is by using the goto.google.com/git-numberer
95  // Gerrit plugin. Other solutions can be used as well, so long
96  // as the same scheme is used consistently for a ref.
97  // Mandatory.
98  int64 position = 5;
99}
100
101// A Gerrit patchset.
102message GerritChange {
103  // Gerrit hostname, e.g. "chromium-review.googlesource.com".
104  string host = 1;
105  // Gerrit project, e.g. "chromium/src".
106  string project = 2;
107  // Change number, e.g. 12345.
108  int64 change = 3;
109  // Patch set number, e.g. 1.
110  int64 patchset = 4;
111}
112
113// Deprecated: Use GitilesCommit instead.
114message CommitPosition {
115  // The following fields identify a git repository and a ref within which the
116  // numerical position below identifies a single commit.
117  string host = 1;
118  string project = 2;
119  string ref = 3;
120
121  // The numerical position of the commit in the log for the host/project/ref
122  // above.
123  int64 position = 4;
124}
125
126// Deprecated: Do not use.
127message CommitPositionRange {
128  // The lowest commit position to include in the range.
129  CommitPosition earliest = 1;
130
131  // Include only commit positions that that are strictly lower than this.
132  CommitPosition latest = 2;
133}
134
135// A range of timestamps.
136//
137// Currently unused.
138message TimeRange {
139  // The oldest timestamp to include in the range.
140  google.protobuf.Timestamp earliest = 1;
141
142  // Include only timestamps that are strictly older than this.
143  google.protobuf.Timestamp latest = 2;
144}
145
146
147// Represents a reference in a source control system.
148message SourceRef {
149  // The source control system used.
150  // Only gitiles is supported at this moment. If other systems need to be
151  // supported in future (e.g. non-gitiles git, subversion, google storage
152  // buckets), they can be added here
153  oneof system {
154    // A branch in gitiles repository.
155    GitilesRef gitiles = 1;
156  }
157}
158
159// Represents a branch in a gitiles repository.
160message GitilesRef {
161  // The gitiles host, e.g. "chromium.googlesource.com".
162  string host = 1;
163
164  // The project on the gitiles host, e.g. "chromium/src".
165  string project = 2;
166
167  // Commit ref, e.g. "refs/heads/main" from which the commit was fetched.
168  // Not the branch name, use "refs/heads/branch"
169  string ref = 3;
170}
171