summercms/docs/plugins/marketplace.md

title, description, section, order

title	description	section	order
Publishing plugins	Describe a plugin for the marketplace with a generated plugin.yaml, keep it current with summer plugin:manifest --check, and read the registry API.	plugins	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.

# 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: a string literal or a constant (of the same package, of another package of the module, or of a required module). The command reads the source and never runs it; any other expression, such as a function call or a variable, is an error naming ID().
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 (literals or constants, as for id), with the version go.mod requires its module at. A requirement at v0.0.0 is an error, because nobody can install that version; a pseudo-version is accepted with a warning. 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:

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:

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:

summer plugin:manifest --check

Run it before tagging a release, so the tag carries a manifest that matches its code.

Testing the manifest in your plugin

Add one test to the plugin, so go test fails as soon as plugin.yaml no longer matches the code. It imports git.golem15.com/golem15/summercms/modules/kiosk and passes the plugin directory, which is "." in a plugin's own package (the framework's copy below checks a fixture):

// TestPluginManifest is the test a plugin repository adds next to its
// plugin.go, with "." as the directory. Here it guards the committed
// manifest of the literal fixture.
func TestPluginManifest(t *testing.T) {
	kiosk.CheckT(t, "testdata/literal")
}

kiosk.CheckT runs the same check as summer plugin:manifest --check and names the command to rerun. A nested plugin gets its own test in its own directory.