diff --git a/docs/commands/develop.md b/docs/commands/develop.md new file mode 100644 index 000000000..5484a4220 --- /dev/null +++ b/docs/commands/develop.md @@ -0,0 +1,14 @@ +# dtm develop + +`dtm develop` is used to develop a new plugin for anything. + +## Brief + +`dtm develop create-plugin` generates plugin scaffolding based on dtm [pre-built templates](https://github.com/devstream-io/devstream/tree/main/internal/pkg/develop/plugin/template). + +`dtm develop validate-plugin` is used for validating an existing plugin or all plugins. + +## Full Process Guide + +A detailed guide to the plugin development process can be found in [creating-a-plugin](https://docs.devstream.io/en/latest/contributing/creating-a-plugin/). + diff --git a/docs/contributing/creating-a-plugin.md b/docs/contributing/creating-a-plugin.md index 7d35c4269..32c86646a 100644 --- a/docs/contributing/creating-a-plugin.md +++ b/docs/contributing/creating-a-plugin.md @@ -4,9 +4,31 @@ First, please read our [CONTRIBUTING](https://github.com/devstream-io/devstream/blob/main/CONTRIBUTING.md) doc. -## 1 Interfaces +## 1 Scaffolding Automagically -### 1.1 Definition +Run `dtm develop create-plugin --name=YOUR-PLUGIN-NAME` , and dtm will automatically generate the following file. + +> ### /cmd/plugin/YOUR-PLUGIN-NAME/main.go + +This is the only main entrance to the plugin code. + +You do not need to change this file. If you want, feel free to submit a pull request to change the [plugin template](https://github.com/devstream-io/devstream/blob/main/internal/pkg/develop/plugin/template/main.go) directly. + +> ### /docs/plugins/YOUR-PLUGIN-NAME.md + +This is the automatically generated plugin documentation. + +Although dtm is automagic, but it can’t read your mind. I’m afraid that you will have to write your own doc. + +> ### /internal/pkg/plugin/YOUR-PLUGIN-NAME/ + +Please fill in the main logic of the plugin here. + +You can check out our [Standard Go Project Layout](project-layout) document for detailed instruction on the project layout. + +## 2 Interfaces + +### 2.1 Definition Each plugin needs to satisfy all the interfaces defined in the [plugin engine](https://github.com/devstream-io/devstream/blob/main/internal/pkg/pluginengine/plugin.go#L10). @@ -17,7 +39,7 @@ At the moment, there are 4 interfaces, which might be subject to change. Current - [`Update`](https://github.com/devstream-io/devstream/blob/main/internal/pkg/pluginengine/plugin.go#L14) - [`Delete`](https://github.com/devstream-io/devstream/blob/main/internal/pkg/pluginengine/plugin.go#L16) -### 1.2 Return Value +### 2.2 Return Value `Create`, `Read`, and `Update` interfaces return two values `(map[string]interface{}, error)`; the first being the "state". @@ -25,10 +47,10 @@ At the moment, there are 4 interfaces, which might be subject to change. Current If no error occurred, the return value would be `(true, nil)`. Otherwise, the result would be `(false, error)`. -## 2 Package +## 3 How does plugin work? -TL;DR: each plugin should have a separate folder under the `cmd/` directory. Refer to [this example](https://github.com/devstream-io/devstream/blob/main/cmd/plugin/githubactions-golang/main.go). +DevStream uses [go plugin](https://pkg.go.dev/plugin) to implement custom DevOps plugins. -Put most of a plugin's code under the `internal/pkg/` directory and only use `cmd/` as the main entrance to the plugin code. +When you execute a command which calls any of the interfaces(`Create`, `Read`, `Update`, `Delete`), devstream's pluginengine will call the [`plugin.Lookup("DevStreamPlugin")` function](https://github.com/devstream-io/devstream/blob/38307894bbc08f691b2c5015366d9e45cc87970c/internal/pkg/pluginengine/plugin_helper.go#L28) to load the plugin, get the variable `DevStreamPlugin` that implements the ` DevStreamPlugin` interface, and then you can call the corresponding plugin logic functions. This is why it is not recommended to modify the `/cmd/plugin/YOUR-PLUGIN-NAME/main.go` file directly. -Check out our [Standard Go Project Layout](project-layout) document for detailed instruction on the project layout. +Note: The `main()` in `/cmd/plugin/YOUR-PLUGIN-NAME/main.go` file will not executed, it is only used to avoid the goclangci-lint error. diff --git a/mkdocs.yml b/mkdocs.yml index 46a441250..caf2c4484 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -19,6 +19,7 @@ nav: - 'commands/verify.md' - 'commands/delete.md' - 'commands/destroy.md' + - 'commands/develop.md' - Core Concepts: - 'core-concepts/core-concepts.md' - 'core-concepts/config.md'