Merge "Add protobuf definition for METADATA files."

// Copyright 2021 Google Inc. All rights reserved.

//

// Licensed under the Apache License, Version 2.0 (the "License");

// you may not use this file except in compliance with the License.

// You may obtain a copy of the License at

//

//     http://www.apache.org/licenses/LICENSE-2.0

//

// Unless required by applicable law or agreed to in writing, software

// distributed under the License is distributed on an "AS IS" BASIS,

// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

// See the License for the specific language governing permissions and

// limitations under the License.

package {

    default_applicable_licenses: ["Android-Apache-2.0"],

}

bootstrap_go_package {

    name: "project_metadata_proto",

    pkgPath: "android/soong/compliance/project_metadata_proto",

    srcs: ["project_metadata.pb.go"],

    deps: [

        "golang-protobuf-reflect-protoreflect",

        "golang-protobuf-runtime-protoimpl",

    ],

}

// Copyright (C) 2022 The Android Open Source Project

//

// Licensed under the Apache License, Version 2.0 (the "License");

// you may not use this file except in compliance with the License.

// You may obtain a copy of the License at

//

//      http://www.apache.org/licenses/LICENSE-2.0

//

// Unless required by applicable law or agreed to in writing, software

// distributed under the License is distributed on an "AS IS" BASIS,

// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

// See the License for the specific language governing permissions and

// limitations under the License.

// A proto definition used to parse METADATA file in third party projects.

// This proto will only contain fields and values used by android compliance.

// It is not intended to be the formal definition of METADATA file.

// See google3/third_party/metadata.proto if you need to add more stuff to

// match upstream. Do not add new fields and values here. Add them upstream

// when necessary, and copy them here.

syntax = "proto2"; // As long as upstream is proto2...

package project_metadata;

option go_package = "android/soong/compliance/project_metadata_proto";

// Definitions for project metadata. (go/thirdparty/metadata)

// Special naming conventions:

// Repeated fields should have singular names (instead of plural).

message Metadata {

  // Name of this API/package.

  optional string name = 1;

  // A short description (a few lines) of the package. It will be

  // included on the summary page.

  // Example: "Handles location lookups, throttling, batching, etc."

  optional string description = 3;

  // Specifies additional data about third-party packages.

  optional ThirdParty third_party = 13;

}

message ThirdParty {

  // The name and description for the package should be specified using the top

  // level fields in MetaData above

  //

  // Description should only specify a short description (a few lines) of the

  // packages. Instructions for maintainers or similar information should be

  // specified in BUILD comments, a separate README.md file, etc.

  // URL(s) associated with the package.

  //

  // At a minimum, all packages must specify a URL which identifies where it

  // came from, containing a type of: ARCHIVE, GIT, PIPER, or OTHER. Typically,

  // a package should contain only a single URL from these types.  Occasionally,

  // a package may be broken across multiple archive files for whatever reason,

  // in which case having multiple ARCHIVE URLs is okay.  However, this should

  // not be used to combine different logical packages that are versioned and

  // possibly licensed differently.

  repeated URL url = 1;

  // The package version.  In order of preference, this should contain:

  //  - If the package comes from Git or another source control system,

  //    a specific tag or revision in source control, such as "r123" or

  //    "58e27d2".  This MUST NOT be a mutable ref such as a branch name.

  //  - a released package version such as "1.0", "2.3-beta", etc.

  //  - the date the package was retrieved, formatted as "As of YYYY-MM-DD".

  optional string version = 2;

  // The date of the change in which the package was last upgraded from

  // upstream.

  // This should only identify package upgrades from upstream, not local

  // modifications. This may identify the date of either the original or

  // merged change.

  //

  // Note: this is NOT the date that this version of the package was released

  // externally.

  optional Date last_upgrade_date = 10;

  // License type that identifies how the package may be used. See

  // go/thirdpartylicenses for instructions on selecting the appropriate type.

  optional LicenseType license_type = 4;

  // Description of local changes that have been made to the package.  This does

  // not need to (and in most cases should not) attempt to include an exhaustive

  // list of all changes, but may instead direct readers to review the local

  // commit history, a collection of patch files, a separate README.md (or

  // similar) document, etc.

  // Note: Use of this field to store IDs of advisories fixed with a backported

  // patch is deprecated, use "security.mitigated_security_patch" instead.

  optional string local_modifications = 6;

  // The URL for any public mirror created for compliance purposes.

  // See go/thirdpartylicenses#reciprocal policy for more details.

  optional string compliance_mirror_url = 12;

  // The homepage for the package. This will eventually replace

  // `url { type: HOMEPAGE }`

  optional string homepage = 14;

}

// URL associated with a third-party package.

message URL {

  enum Type {

    // The homepage for the package. For example, "https://bazel.io/". This URL

    // is optional, but encouraged to help disambiguate similarly named packages

    // or to get more information about the package. This is especially helpful

    // when no other URLs provide human readable resources (such as git:// or

    // sso:// URLs).

    HOMEPAGE = 1;

    // The URL of the archive containing the source code for the package, for

    // example a zip or tgz file.

    ARCHIVE = 2;

    // The URL of the upstream git repository this package is retrieved from.

    // For example:

    //  - https://github.com/git/git.git

    //  - git://git.kernel.org/pub/scm/git/git.git

    //

    // Use of a git URL requires that the package "version" value must specify a

    // specific git tag or revision.

    GIT = 3;

    // The URL of the upstream SVN repository this package is retrieved from.

    // For example:

    //  - http://llvm.org/svn/llvm-project/llvm/

    //

    // Use of an SVN URL requires that the package "version" value must specify

    // a specific SVN tag or revision.

    SVN = 7;

    // The URL of the upstream mercurial repository this package is retrieved

    // from. For example:

    //   - https://mercurial-scm.org/repo/evolve

    //

    // Use of a mercurial URL requires that the package "version" value must

    // specify a specific tag or revision.

    HG = 8;

    // The URL of the upstream darcs repository this package is retrieved

    // from. For example:

    //   - https://hub.darcs.net/hu.dwim/hu.dwim.util

    //

    // Use of a DARCS URL requires that the package "version" value must

    // specify a specific tag or revision.

    DARCS = 9;

    // The URL of the upstream piper location.  This is primarily used when a

    // package is being migrated into third_party from elsewhere in piper, or

    // when a package is being newly developed in third_party.  For newly

    // developed packages, the PIPER URL should reference the package itself

    // (e.g. "http://google3/third_party/my/package")

    PIPER = 4;

    // A URL that does not fit any other type. This may also indicate that the

    // source code was received via email or some other out-of-band way. This is

    // most commonly used with commercial software received directly from the

    // vendor. In the case of email, the URL value can be used to provide

    // additional information about how it was received.

    OTHER = 11;

    // The URL identifying where the local copy of the package source code can

    // be found.

    //

    // Typically, the metadata files describing a package reside in the same

    // directory as the source code for the package. In a few rare cases where

    // they are separate, the LOCAL_SOURCE URL identifies where to find the

    // source code. This only describes where to find the local copy of the

    // source; there should always be an additional URL describing where the

    // package was retrieved from.

    //

    // Examples:

    //  - http://google3/third_party/java_src/gerritcodereview/gerrit/

    //  - https://android.googlesource.com/platform/external/apache-http/

    LOCAL_SOURCE = 6;

  }

  // The type of resource this URL identifies.

  optional Type type = 1;

  // The actual URL value.  URLs should be absolute and start with 'http://' or

  // 'https://' (or occasionally 'git://' or 'ftp://' where appropriate).

  optional string value = 2;

}

// License type that identifies how the packages may be used. See

// go/thirdpartylicenses for full explanation of each license type.

enum LicenseType {

  BY_EXCEPTION_ONLY = 1;

  NOTICE = 2;

  PERMISSIVE = 3;

  RECIPROCAL = 4;

  RESTRICTED_IF_STATICALLY_LINKED = 5;

  RESTRICTED = 6;

  UNENCUMBERED = 7;

}

// Represents a whole or partial calendar date, such as a birthday. The time of

// day and time zone are either specified elsewhere or are insignificant. The

// date is relative to the Gregorian Calendar. This can represent one of the

// following:

//

// * A full date, with non-zero year, month, and day values.

// * A month and day, with a zero year (for example, an anniversary).

// * A year on its own, with a zero month and a zero day.

// * A year and month, with a zero day (for example, a credit card expiration

//   date).

message Date {

  // Year of the date. Must be from 1 to 9999, or 0 to specify a date without

  // a year.

  optional int32 year = 1;

  // Month of a year. Must be from 1 to 12, or 0 to specify a year without a

  // month and day.

  optional int32 month = 2;

  // Day of a month. Must be from 1 to 31 and valid for the year and month, or 0

  // to specify a year by itself or a year and month where the day isn't

  // significant.

  optional int32 day = 3;

}