From 78580a42e1a00355e97786c9d10ea24aabff9fda Mon Sep 17 00:00:00 2001 From: Wilken Rivera Date: Mon, 20 Nov 2023 19:07:07 +0000 Subject: [PATCH] backport of commit 72bc6c811a6ecb808bc5a746eea08fbbea37d3db --- .github/ISSUE_TEMPLATE/plugin_integration.md | 21 +++++ .../content/docs/plugins/creation/index.mdx | 94 +++++-------------- 2 files changed, 42 insertions(+), 73 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/plugin_integration.md diff --git a/.github/ISSUE_TEMPLATE/plugin_integration.md b/.github/ISSUE_TEMPLATE/plugin_integration.md new file mode 100644 index 00000000000..c84da673895 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/plugin_integration.md @@ -0,0 +1,21 @@ +--- +name: Plugin Integration Request +about: Open request to add your plugin as a Packer integration (https://developer.hashicorp.com/packer/integrations) +labels: integration-request +--- + +#### Description + +A written description of your plugin along with a link to the plugin repository. + +#### Integration Tier + + +#### Checklist +- [] Has valid [`metadata.hcl`](https://github.com/hashicorp/integration-template) file in plugin repository. +- [] Has added integration scripts [packer-plugin-scaffolding](https://github.com/hashicorp/packer-plugin-scoffolding) to plugin repository. +- [] Has added top-level integration README.md file to plugin `docs` directory. +- [] All plugins components have one README.md describing their usage. +- [] Has a fully synced `.web-docs` directory ready for publishing to the integrations portal. + diff --git a/website/content/docs/plugins/creation/index.mdx b/website/content/docs/plugins/creation/index.mdx index 32537f160d3..3ba19fee600 100644 --- a/website/content/docs/plugins/creation/index.mdx +++ b/website/content/docs/plugins/creation/index.mdx @@ -214,87 +214,35 @@ Here's what you need to create releases using GitHub Actions: to install a plugin using `packer init`, see the [init docs](/packer/docs/commands/init). -## Registering Plugin Documentation +## Registering Plugins -~> Note: Registering a remote plugin's plugin documentation requires the use of [Packer's plugin docs configuration](https://github.com/hashicorp/packer-plugin-scaffolding/tree/main/docs). +~> Note: Registering a remote as an integration requires the use of [Packer's plugin docs configuration](https://github.com/hashicorp/packer-plugin-scaffolding/tree/main/docs). -`packer init` allows users to require and install remote Packer plugins, those not bundled with Packer core, that have been published to GitHub automatically. -To help with the discovery of remote Packer plugins on GitHub, plugins maintainers can choose to register plugin documentation for each component directly on the [Packer Documentation Page](/packer/docs). +`packer init` allows users to require and install remote Packer plugins published to GitHub. +To help with the discovery of remote Packer plugins, plugins maintainers can choose to register their plugin as a [Packer Integration](/packer/integrations). -The registration process requires the creation of a `docs.zip` file archive containing the `.mdx` files for each of the plugin components in the remote plugin's repository. A working example can be seen at the [packer-plugin-docker repository](https://github.com/hashicorp/packer-plugin-docker/releases/latest). +The registration process requires [metadata configuration](https://github.com/hashicorp/integration-template#metadata-configuration) be added to your plugin repository for configuring the Packer integration pipeline and plugin documentation for rendering +on the [Packer Integrations](/packer/integrations) portal. -Once in place the remote plugin can be added to Packer's website builds by opening a pull-request against [hashicorp/packer](https://github.com/hashicorp/packer), with the needed configuration for pulling in the remote documentation. +The following steps are required for registering your plugin as an integration -Remote plugins will have their components listed under the respected types (i.e builders, provisioners, etc) using the names specified in the remote block configuration, and labeled with their respective [tier and namespace](/packer/docs/plugins#tiers-and-namespaces). +1. Update your plugin documentation structure according to the templated defined with the [Packer Plugin Scaffolding template]. +New plugins generated from this template may have the necessary structure in place. If so you can jump to step 4. +1. For the integrations library, only one top-level README per integration is supported. Any top-level index.mdx files that exist +within a plugins existing documentation will need to migrate to a top-level README. +1. Update your top-level integration README to include a description, plugin installation steps, available components section, and, any, additional sections +needed to inform users on how to work with your integration. Refer to [Packer scaffolding plugin](https://github.com/hashicorp/packer-plugin-scaffolding/blob/main/docs/README.md) for an example. +1. Update the top-level README for each of the components within your integration to follow the structure defined in the scaffolding template. +1. Open a request for integration issue with the Packer team - [Open Request](https://github.com/hashicorp/packer/issues/new/choose). +Please provide all the requested information to help expedite the integration request. -To register a plugin follow one of the following setups +By opening an integration request, you are asking a member of the to Packer team to review your plugin integration configuration, plugin documentation, +and, finally, to open an internal pull-request to finalize the integration setup. - - - -Documentation for a plugin is maintained within the `docs` directory and served on GitHub. - -To include plugin docs on the website, a global pre-hook has been added to the main scaffolding [.goreleaser.yml](https://github.com/hashicorp/packer-plugin-scaffolding/blob/42e5b0b1e575879b0477cb6d4291e027f4d92f85/.goreleaser.yml#L10) file, that if uncommented will generate and include a docs.zip file as part of the plugin release. - -The `docs.zip` file contains all of the `.mdx` files under the plugins root `docs/` directory that the website can consume remotely. - - - - - -You can generate the required documentation structure manually by creating a zip file called `docs.zip` of the docs directory and including that zip file in the plugin release. - -```/bin/bash -[[ -d docs/ ]] && zip -r docs.zip docs/ -``` - - - - -Once the first `docs.zip` file has been included into a release you will need to open a one time pull-request against [hashicorp/packer](https://github.com/hashicorp/packer) to register the plugin docs. - -This is done by adding the block below for the respective plugin to the file [website/data/plugins-manifest.json](https://github.com/hashicorp/packer/blob/main/website/data/plugins-manifest.json). - -```json -{ - "title": "Scaffolding", - "path": "scaffolding", - "repo": "hashicorp/packer-plugin-scaffolding", - "version": "latest", - "sourceBranch": "main" -} -``` - -If a plugin maintainer wishes to only include a specific version of released docs, then the `"version"` key in the above configuration should be set to a released version of the plugin. Otherwise it should be set to `"latest"`. - -The `"sourceBranch"` key in the above configuration ensures potential contributors can link back to source files in the plugin repository from the Packer docs site. If a `"sourceBranch"` value is not present, it will default to `"main"`. - -### Testing Plugin Documentation - -Before publishing the `docs.zip` file, you might want to preview your documentation changes. -We provide a mechanism that allows to preview how the docs will look like within -the Packer documentation. - -Follow the next steps to get the Packer website running and preview the documentation changes: - -- Get the [Packer source code](https://github.com/hashicorp/packer). Our website code is under the [website folder](https://github.com/hashicorp/packer/tree/main/website). -- Generate the `docs.zip` file. You can find above the steps to do so. -- Add the `zipFile` attribute to the plugin entry in `plugins-manifest.json`. The value should be the full path of the `docs.zip` generated. For example: - -```json -{ - "title": "Scaffolding", - "path": "scaffolding", - "repo": "hashicorp/packer-plugin-scaffolding", - "version": "latest", - "sourceBranch": "main", - "zipFile": "/Users/myuser/Packer/plugins/packer-plugin-scaffolding/docs.zip" -} -``` +Plugin integrations will be listed as a [Packer Integration](/packer/integrations), with details on how to install and use your the plugin. -- Go to the [website folder](https://github.com/hashicorp/packer/tree/main/website). - In the website README, follow the steps to [run the website with node](https://github.com/hashicorp/packer/tree/main/website#with-node). -- Once the website is up and running, the plugin documentation should be available in `http://localhost:3000/docs`. +Plugin integrations, once deployed, can be updated manually, or automatically upon a new release, by the plugin authors. Changes to the defined documentation structure +or parent repository should be communicated to the Packer team to ensure a working integration pipeline. ## Plugin Development Tips and FAQs