使用元数据文件定义 Fuchsia 软件包信息

简介

Fuchsia 的 Gerrit 安装支持自定义结构化元数据文件。这些文件旨在：

  • 简单易懂，并提供实用信息，例如软件包的名称、说明和规范网址
  • 机器可读（通过将文件定义为使用标准格式定义文件），自动化系统可以使用此格式来执行一些操作，例如自动将审核者添加到 CL，或查找提醒系统应提交问题的错误组件

目前，元数据文件的唯一自动用途是自动将审核者添加到 CL，并在添加/提交 CL 时发送电子邮件通知。如需了解这些内容，请参阅提交前部分。

元数据文件仅适用于第一方代码。

格式

元数据文件包括：

元数据消息类型如下：

syntax = "proto3";

// This proto is located at
// https://github.com/googleapis/googleapis/blob/master/google/type/date.proto
import "google/type/date.proto";

// IssueTracker contains the project configuration for the Google
// Issue Tracker.
message IssueTracker {
  int64 component_id = 1;
}

message Tracker {
  repeated IssueTracker issue_tracker = 2;
  // for_automation defines whether this tracker should be used by automated
  // processes (e.g. alerts).
  bool for_automation = 3;
}

message Presubmit {
  repeated string review_notify = 1;
  repeated string auto_reviewers = 2;
}

message Metadata {
  // name is the name of the API/Package/Program.
  string name = 1;
  string description = 2;
  // url points to some documentation/landing page.
  string url = 3;
  // Date this metadata was last reviewed by a human.
  google.type.Date last_reviewed_date = 4;
  repeated Tracker trackers = 5;
  // presubmits are used for defining presubmits.
  // The field is marked repeated for future expansion, but only
  // one message should be used.
  repeated Presubmit presubmits = 6;
}

下面是一个元数据文件的虚构示例：

name: "Fuchsia source code automation"
description: "A binary for automating source code gardening tasks"
url: "https://fuchsia.dev"
last_reviewed_date: {
    year: 2022
    month: 1
    day: 23
}
trackers: {
  issue_tracker: {
    component_id: 1478090
  }
}

presubmits: {
  auto_reviewers: "frodo@example.com"

  review_notify: "sauron@example.com"
  review_notify: "gandalf@example.com"
}

多个元数据文件

为了支持包含多个不同项目的大型代码库，可在整个文件树中使用多个 METADATA.textproto 文件。元数据文件适用于其自己的目录以及以下所有目录。

提交前

presubmit 字段用于指定应将哪些审核者作为审核者自动添加到每个更改列表 (auto_reviewers)，以及应在上传/提交更改列表后收到电子邮件通知的审核者 (review_notify)。

以下是包含多个元数据文件的层次结构示例：

├── alice
│   ├── METADATA.textproto
│   └── README.md
├── foo
│   └── bar
│       ├── baz
│       │   └── METADATA.textproto
│       │   └── server.go
│       └── METADATA.textproto
│       └── hello.rs
├── METADATA.textproto
└── README.md

每当整个仓库中的任何文件发生更改时，系统都会添加/通知 /METADATA.textproto 中指定的审核者。/foo/bar/METADATA.textproto 中的审核者适用于 /foo/bar 目录以及子目录 /foo/bar/baz 中的所有内容。/foo/bar/baz/METADATA.textproto 中的审核者仅适用于在 /foo/bar/baz/ 目录中修改的文件。

与其他文件的关系

元数据文件与其他文件没有任何关系，例如 OWNERS（用于指定目录的所有者）或 README.fuchsia（用于定义第三方代码的元数据）。