Separate section for buf.plugin.yaml (#292)

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/<org>/<name>`) with information on how to detect new plugin versions.
+    * Plugins should include a `source.yaml` at the top-level directory (i.e. `plugins/<org>/<name>`)
+    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