ec6a1955fc
- new module kiosk: Manifest, Marshal, Parse, Derive, Generate, Write, Check, StaleError - plugin:manifest [dir] with --check, --pretend, --name, --description - docs: kiosk README, root table row, plugins/marketplace.md, scaffolding row
75 lines
3.7 KiB
Markdown
75 lines
3.7 KiB
Markdown
---
|
|
title: Publishing plugins
|
|
description: Describe a plugin for the marketplace with a generated plugin.yaml, keep it current with summer plugin:manifest --check, and read the registry API.
|
|
section: plugins
|
|
order: 50
|
|
---
|
|
# Publishing plugins
|
|
|
|
A plugin that lives in its own repository can be listed on the SummerCMS marketplace. The listing reads one file from the repository, `plugin.yaml`, which the `summer` tool generates from the plugin's own sources. Nothing in it is typed by hand, so the ID, module path and version requirements the marketplace shows are the ones the code has.
|
|
|
|
This is the counterpart of WinterCMS's `pluginDetails()` in `Plugin.php` together with the `composer.json` a marketplace plugin carries.
|
|
|
|
## The plugin.yaml manifest
|
|
|
|
`plugin.yaml` sits next to `plugin.go`, one per plugin package. A repository whose module holds a second plugin in a subdirectory has a second `plugin.yaml` in that subdirectory.
|
|
|
|
```yaml
|
|
# Generated by summer plugin:manifest. Do not edit; rerun the command.
|
|
schema: 1
|
|
id: acme.blog
|
|
module: example.com/acme/sm-blog-plugin
|
|
package: example.com/acme/sm-blog-plugin
|
|
name: Blog
|
|
description: Posts, categories and a feed for SummerCMS applications.
|
|
framework: v0.6.0
|
|
requires:
|
|
acme.translate: v0.2.0
|
|
overrides:
|
|
name: Blog
|
|
```
|
|
|
|
| Field | Comes from |
|
|
|-------|------------|
|
|
| `schema` | The format version (`kiosk.SchemaVersion`). A reader that knows an older schema refuses the file and asks you to update `summer`. |
|
|
| `id` | What `ID()` in `plugin.go` returns. |
|
|
| `module` | The `module` line of the nearest `go.mod`: what `go get` takes. |
|
|
| `package` | The plugin's import path: what `summer.yaml` lists. It differs from `module` for a plugin in a subdirectory. |
|
|
| `name` | The README's H1, or the `--name` override. |
|
|
| `description` | The first paragraph after the README's H1 (the one-sentence summary of the standard README structure), or the `--description` override. |
|
|
| `framework` | The version `go.mod` requires the framework (`git.golem15.com/golem15/summercms`) at: the oldest framework release the plugin works with. |
|
|
| `requires` | Each plugin ID `Requires()` returns, with the version `go.mod` requires its module at. The value is empty for a plugin in the same module, and for one whose module is not a `go.mod` require. Left out when `Requires()` returns none. |
|
|
| `overrides` | The `--name` and `--description` values, kept across regenerations. Left out when neither is set. |
|
|
|
|
Versions are minimums in Go's sense (`v0.6.0` means "v0.6.0 or newer"), never ranges: Go's minimal version selection picks the version, and a major version change moves the module path.
|
|
|
|
## Generating and checking it
|
|
|
|
Run `summer plugin:manifest` in the plugin directory, or pass the directory:
|
|
|
|
```sh
|
|
summer plugin:manifest
|
|
summer plugin:manifest plugins/acme/blog
|
|
summer plugin:manifest --pretend
|
|
```
|
|
|
|
`--pretend` prints the file instead of writing it. Commit `plugin.yaml`, and rerun the command after changing what it reads: the README's H1 or summary, `ID()` or `Requires()`, or a `go.mod` require.
|
|
|
|
A README whose H1 is the plugin ID (`# acme.blog`) has no display name to offer, so the command stops and asks for one. Give it once; it is stored under `overrides:` and reused:
|
|
|
|
```sh
|
|
summer plugin:manifest --name="Blog"
|
|
summer plugin:manifest --description="Posts, categories and a feed."
|
|
summer plugin:manifest --name=""
|
|
```
|
|
|
|
The last line clears the name override, so the README's H1 is used again.
|
|
|
|
`--check` writes nothing. It regenerates the manifest in memory and exits with status 1, printing what it expected, when `plugin.yaml` is missing or differs from the committed file:
|
|
|
|
```sh
|
|
summer plugin:manifest --check
|
|
```
|
|
|
|
Run it before tagging a release, so the tag carries a manifest that matches its code.
|