doc: Add more details to the guide on publishing plugins #15753
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
erezrokah
requested changes
Dec 19, 2023
website/pages/docs/developers/publishing-a-plugin-to-the-hub.mdx
Outdated
Show resolved
Hide resolved
website/pages/docs/developers/publishing-a-plugin-to-the-hub.mdx
Outdated
Show resolved
Hide resolved
|
|
||
| <img src="/images/docs/publishing-plugins/create-team.png" width="50%" style={{margin:"1em"}} /> | ||
|
|
||
| The display name will be visible on Hub next to your plugin. The team name is going to be used in configs to reference your plugin using `team-name/plugin-name`. |
There was a problem hiding this comment.
Suggested change
| The display name will be visible on Hub next to your plugin. The team name is going to be used in configs to reference your plugin using `team-name/plugin-name`. | |
| The display name will be visible on Hub next to your plugin. The team name is going to be used in configurations to reference your plugin using `<team-name>/<plugin-name>`. |
We often use <> to denote a value the user should replace
| 5. Once you're ready run `cloudquery plugin publish -f` to publish a non draft version of the plugin. This version will be immutable and will show up in <https://hub.cloudquery.io/>. Allow up to 1 hour for the Hub to reflect the changes | ||
| 1. (Optional, recommended) In the root directory of your plugin repository run `git tag v1.0.0` to tag the version you're about to publish (replace `v1.0.0` with the version you'd like to publish). | ||
| 2. (Optional, recommended) Run `git push origin v1.0.0` to push the tag. | ||
| 3. Run `go run main.go package --docs-dir docs -m 'feat: Initial release' v1.0.0 .` to package the plugin. `v1.0.0` should match the tag you created in step 1. The `-m` specifies the changelog message that will be used in the release notes and it supports markdown. See example [here](https://hub.cloudquery.io/plugins/.source/cloudquery/alicloud/v4.0.14/versions). `docs` should be a directory containing markdown files that serve as documentation for the plugin. Read more about the documentation format [here](#documentation-format). |
There was a problem hiding this comment.
Suggested change
| 3. Run `go run main.go package --docs-dir docs -m 'feat: Initial release' v1.0.0 .` to package the plugin. `v1.0.0` should match the tag you created in step 1. The `-m` specifies the changelog message that will be used in the release notes and it supports markdown. See example [here](https://hub.cloudquery.io/plugins/.source/cloudquery/alicloud/v4.0.14/versions). `docs` should be a directory containing markdown files that serve as documentation for the plugin. Read more about the documentation format [here](#documentation-format). | |
| 3. Run `go run main.go package --docs-dir docs -m 'feat: Initial release' v1.0.0 .` to package the plugin. `v1.0.0` should match the tag you created in step 1. The `-m` specifies the changelog message that will be used in the release notes and it supports markdown. See example [here](https://hub.cloudquery.io/plugins/source/cloudquery/alicloud/v4.0.14/versions). `docs` should be a directory containing markdown files that serve as documentation for the plugin. Read more about the documentation format [here](#documentation-format). |
I believe this dot breaks the link
| 1. (Optional, recommended) In the root directory of your plugin repository run `git tag v1.0.0` to tag the version you're about to publish (replace `v1.0.0` with the version you'd like to publish). | ||
| 2. (Optional, recommended) Run `git push origin v1.0.0` to push the tag. | ||
| 3. Run `go run main.go package --docs-dir docs -m 'feat: Initial release' v1.0.0 .` to package the plugin. `v1.0.0` should match the tag you created in step 1. The `-m` specifies the changelog message that will be used in the release notes and it supports markdown. See example [here](https://hub.cloudquery.io/plugins/.source/cloudquery/alicloud/v4.0.14/versions). `docs` should be a directory containing markdown files that serve as documentation for the plugin. Read more about the documentation format [here](#documentation-format). | ||
| 4. Run `cloudquery plugin publish` to publish a draft version of the plugin. The version will show up under the versions tab of your plugin in (https://cloud.cloudquery.io). As long as the version is in draft it's mutable and you can re-package the plugin and publish it again. |
There was a problem hiding this comment.
Suggested change
| 4. Run `cloudquery plugin publish` to publish a draft version of the plugin. The version will show up under the versions tab of your plugin in (https://cloud.cloudquery.io). As long as the version is in draft it's mutable and you can re-package the plugin and publish it again. | |
| 4. Run `cloudquery plugin publish` to publish a draft version of the plugin. The version will show up under the versions tab of your plugin in <https://cloud.cloudquery.io>. As long as the version is in draft it's mutable and you can re-package the plugin and publish it again. |
For bare URLs we should use <> otherwise they look like this:
There was a problem hiding this comment.
fixed so it's not bare
How do I add the HTML to markdown? The html |
Co-authored-by: Erez Rokah <erezrokah@users.noreply.github.com>
Co-authored-by: Erez Rokah <erezrokah@users.noreply.github.com>
disq
reviewed
Dec 20, 2023
disq
approved these changes
Dec 20, 2023
erezrokah
approved these changes
Dec 21, 2023
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Adding a bit more detail to the guide on publishing plugins - what the team name/display name is, and how to use the plugin visibility and release stage for staging plugin releases.