From 73d64df91f3873252afc104b405d1eeebd5d535f Mon Sep 17 00:00:00 2001 From: Michael Fridman Date: Wed, 4 Jan 2023 16:00:55 -0500 Subject: [PATCH] Separate section for buf.plugin.yaml (#292) --- CONTRIBUTING.md | 36 +++++++++++++++++++++++++++--------- 1 file changed, 27 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9bc634171..e7d80b7ed 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,7 +10,7 @@ This document provides details for Buf developers on how to contribute to this r The build requires the following: * [Go](https://go.dev/dl/) (1.19+) -* [Buf](https://github.com/bufbuild/buf) (1.8.0+) +* [Buf](https://github.com/bufbuild/buf) (1.11.0+) * [yq](https://github.com/mikefarah/yq) ### Makefile targets @@ -48,14 +48,32 @@ This file contains a directory checksum of the generated code for the plugin and * Builds should be reproducible (if possible). All Docker images used for builds should use a specific label (i.e. `debian:bullseye-YYYYMMDD` instead of `debian:bullseye` or `debian`). * NPM/Node: A `package.json` and `package-lock.json` file should be checked in and `npm ci` should be used during installation to ensure consistent dependencies are installed. * Go: Compilation should use `-trimpath`. -* A `buf.plugin.yaml` should include the following: - * `source_url`: Path to the source code URL for the Protobuf plugin. - * `description`: Description of the plugin (shown to the user in the BSR). - * `output_languages`: The output language types generated by the plugin. See the [PluginLanguage](https://github.com/bufbuild/buf/blob/c8fc1a2a8176c69a1176a18741506181fc1edbaf/proto/buf/alpha/registry/v1alpha1/plugin_curation.proto#L30-L47) enum for existing languages. Open a GitHub issue in the [Buf CLI](https://github.com/bufbuild/buf) if the output language isn't found for a plugin. - * `spdx_license_id`: The license id for the plugin from https://spdx.org/licenses/. - * `license_url`: The URL to the license for the release of the plugin. - * If the plugin outputs JavaScript/TypeScript or Go, it is recommended to add a `runtime` section so the plugin can be used with the BSR remote registries. See the `connect-go` or `connect-web` plugins for an example. This is an advanced topic, so feel free to reach out on [Slack](https://buf.build/links/slack) for more information. -* Plugins should include a `source.yaml` at the top-level directory (i.e. `plugins//`) with information on how to detect new plugin versions. + * Plugins should include a `source.yaml` at the top-level directory (i.e. `plugins//`) + with information on how to detect new plugin versions. + +### `buf.plugin.yaml` file + +A `buf.plugin.yaml` file captures metadata about the plugin. It includes mandatory and optional +fields that are displayed on the individual plugin page and the BSR plugin homepage at +https://buf.build/plugins. + +Note, although some fields are optional, it is suggested to include as many as possible. + +**Mandatory:** + +* `version`: The YAML configuration version, must be `v1`. +* `name`: the plugin identity with format `{remote}/{organization_name}/{plugin_name}`. +* `plugin_version`: the plugin version with format`v{semver}`, the `v` prefix is required and the + version must be valid [semantic versioning](https://semver.org/). + +**Optional:** + +* `source_url`: Path to the source code URL for the Protobuf plugin. +* `description`: Description of the plugin (shown to the user in the BSR). +* `output_languages`: The output language types generated by the plugin. See the [PluginLanguage](https://buf.build/bufbuild/buf/docs/main:buf.alpha.registry.v1alpha1#buf.alpha.registry.v1alpha1.PluginLanguage) enum for existing languages. Open a GitHub issue in the [Buf CLI](https://github.com/bufbuild/buf) if the output language isn't found for a plugin. +* `spdx_license_id`: The license id for the plugin from https://spdx.org/licenses/. +* `license_url`: The URL to the license for the release of the plugin. +* If the plugin outputs JavaScript/TypeScript or Go, it is recommended to add a `runtime` section so the plugin can be used with the BSR remote registries. See the `connect-go` or `connect-web` plugins for an example. This is an advanced topic, so feel free to reach out on [Slack](https://buf.build/links/slack) for more information. ## CI/CD