syntax = "proto3";
package results_feed;

import "google/protobuf/timestamp.proto";

// Documentation of the data stored in the dart_ci Firestore database.
// This data is used by result_feed to display and approve new test failures.
// This proto definition file is not actually used in any of the code.
// No generated protobuf code for Dart is created from this.
// This file is currently just documentation.

// Describes a changed result on a test, on one or more configurations,
// that occurs on builds that test the commits in a given blamelist.
// When a test result is reported on a configuration that agrees in
// name, result, and previous result with this record, and the blamelist
// of this test run overlaps the blamelist of this record, then the
// configuration is added to the list of configurations and the blamelist
// is intersected with the blamelist of this run.
message Result {
  // Unique document ID created by Firestore for this document.
  // Not a field in the document.
  string id = 1;
  string name = 2; // The full path of the test, as output by test.py.
  string result = 3; // The new result of the test.

  // The result of the test on builds immediately before these builds.
  string previous_result = 4;

  // The expected result of this test, given in the test source.
  // Some tests are written to produce an error of a specific type.
  // This is not the approval status of the test.
  string expected = 5;

  // The configurations that produced this changed result when tested.
  repeated string configurations = 6;

  // Commits to sdk/master are indexed consecutively in the table 'commits'.
  int32 blamelist_start_index = 7;
  int32 blamelist_end_index = 8;  // Inclusive: this commit is in the blamelist.
  reserved 9;  // Unused

  // Optional: The index of a the commit that is responsible for these changes.
  // Chosen by a user in the results feed UI.
  int32 pinned_index = 10;
  reserved 11, 12;  // Used in TryResult

  bool approved = 13; // May be missing in older records, interpreted as false.

  // Configurations where this result is the latest change to
  // the result of this test are considered active. If a new change comes in,
  // changing the result of this test on a configuration, that configuration is
  // removed from the set active_configurations.
  // The 'active' and 'active_configurations' fields are present only if there
  // are some active configurations remaining.

  // Present, and true, if this result is still active on some configuration.
  bool active = 14;

  // Present only if nonempty. The configurations on which this is
  // the latest change to this test's result.
  repeated string active_configurations = 15;
}

// Similar to a Result message, but representing results from a try builder.
// There is no blamelist. Gerrit CL and patchset numbers identify the build.
message TryResult {
  // Unique document ID created by Firestore for this document.
  string id = 1;
  string name = 2; // The full path of the test, as output by test.py.
  string result = 3; // The new result of the test.

  // The result of the test on builds immediately before these builds.
  string previous_result = 4;

  // The expected result of this test, given in the test source.
  // Some tests are written to produce an error of a specific type.
  // This is not the approval status of the test.
  string expected = 5;

  // The configurations that produced this changed result when tested.
  repeated string configurations = 6;

  // Used in Result.  We may want to merge the two types later.
  reserved 7 to 10;

  // The Gerrit CL number.
  int32 review = 11;
  int32 patchset = 12;

  bool approved = 13;  // May be missing in older records, interpreted as false.
}

// Represents a single build of a CI builder
message Build {
  // The document ID is the concatenation of builder, a colon ':', and index.
  string id = 1;
  int32 build_number = 2; // The build number from buildbucket.
  string builder = 3;
  int32 index = 4; // The index of the commit this build built.
  int32 num_chunks = 5; // The number of chunks of results for this build.
  int32 processed_chunks = 6; // The number of results chunks received.
  // True if no new unapproved failures have been received.
  bool success = 7;
  bool completed = 8;  // True if all chunks have been received.
}

message TryBuild {
  // The document ID is the concatenation of builder, ':', review, ':',
  // and patchset.
  string id = 1;
  int32 build_number = 2;
  string builder = 3;
  reserved 4;
  int32 num_chunks = 5; // The number of chunks of results for this build.
  int32 processed_chunks = 6; // The number of results chunks received.
  // True if no new unapproved failures have been received.
  bool success = 7;
  bool completed = 8;  // True if all chunks have been received.
  int32 review = 9;
  int32 patchset = 10;
  string buildbucket_id = 11;
}

message Commit {
  // The hash of a commit in the dart-sdk repo.
  // Stored as the document ID, not a field.
  string id = 1;

  // The position of the commit in the sdk master branch, only considering
  // the first parent of each commit, a linear chain.
  int32 index = 2;
  string author = 3; // The author of the commit, as an email address.
  google.protobuf.Timestamp created = 4;
  string title = 5; // The first line of the commit message.
  int32 review = 6; // Optional: the id of the review this commit lands.
  string revert_of = 7; // Optional: the hash of the commit this commit reverts.
  string reland_of = 8; // Optional: the hash of the relanded commit.
}

// A map from configuration names to builder names.
// Currently some configurations are on multiple builders, so unstable. Fix.
message Configuration {
  string id = 1; // The name of the configuration. Stored as the document ID.
  string builder = 2;
}

// A Gerrit review. Only the information needed for our display of try results.
message Review {
  string id = 1; // The Gerrit review number (CL number)
  string subject = 2; // The first line of the commit message.
  string revert_of = 3; // Optional: the hash of the commit this review reverts.

  message Patchset {
    string id = 1; // The patchset number.
    string description = 2; // The description of this patchset.

    // The string giving the type of patchset, a rebase, changed commit message,
    //  or a new upload, which is called 'REWORK'.
    string kind = 3;
    int32 number = 4; // Identical to id.

    // The number of the first patchset that differs from this patchset only by
    // rebases and commit message changes.
    int32 patchset_group = 5;
  }

  repeated Patchset patchsets = 3;
  int32 landed_index = 4; // Optional: The index of the commit landing the CL.
}

message Comment {
  // Unique document ID created by Firestore for this document.
  string id = 1;

  // The email address of the user who made this comment/approval.
  string author = 2;

  // The time that the comment/approval was entered
  google.protobuf.Timestamp created = 3;

  // The text of the comment (optional if link is present).
  string comment = 4;
  reserved 5;
  // If approved is true, this comment approves the linked tests
  // If approved is false, it removes any earlier approvals on these tests
  // If the field is missing, it does not change the current approval status
  bool approved = 6;

  // The results that this comment approves or disapproves.
  // The field values are the document IDs of the Result or TryResult records
  // If the comment is just a reply, and does not approve anything, these
  // fields will be missing.
  repeated string results = 7;
  repeated string try_results = 8;
  reserved 9;
  // These are copies of the fields in the results this comment refers to.
  // A comment may belong to both a review and to the commit landing the review.
  // These are the fields from a Result message
  int32 blamelist_start_index = 10;
  int32 blamelist_end_index = 11;
  int32 pinned_index = 12;
  // These are the fields from a TryResult message
  int32 review = 13;
  int32 patchset = 14;
}