From e495213618ec727a72d02b514b3b66f873f51cee Mon Sep 17 00:00:00 2001
From: Zaiming Shi <zmstone@gmail.com>
Date: Sat, 6 Mar 2021 23:12:37 +0100
Subject: [PATCH] chore(build): Add README for lib-extra

---
 lib-extra/README.md | 50 +++++++++++++++++++++++++++++++++++++++++++++
 lib-extra/plugins   |  3 +--
 2 files changed, 51 insertions(+), 2 deletions(-)
 create mode 100644 lib-extra/README.md

diff --git a/lib-extra/README.md b/lib-extra/README.md
new file mode 100644
index 000000000..3196f4b8c
--- /dev/null
+++ b/lib-extra/README.md
@@ -0,0 +1,50 @@
+# EMQ X Extra plugin apps
+
+This directory keeps a `plugins` file which defines all the approved
+external plugins from open-source community.
+
+The (maybe broken) symlinks are keept to help testing plugins
+in this umbrella project.
+
+## How to build `plugin_foo`
+
+Add `plugin_foo` as a rebar3 dependency in `plugins` file.
+
+e.g.
+
+```
+{erlang_plugins,
+  [ {plugin_foo, {git, "https://github.com/bar/plugin-foo.git", {tag, "0.1.0"}}}
+  ]
+}.
+```
+
+Exeucte command
+
+```
+export EMQX_EXTRA_PLUGINS='plugin_foo'
+make
+```
+
+The plugin source code should downloaded to `_build/default/lib/plugin_foo`
+
+NOTE: Shallow clone with depth=1 is used for git dependencies.
+
+## How to test `plugin_foo`
+
+If the source code in `_build` is already symlinked from `lib-extra/`,
+you may directlly run tests with commands below.
+
+```bash
+./rebar3 eunit --dir lib-extra/plugin_foo
+./rebar3 ct --dir lib-extra/plugin_foo
+```
+
+In case the plugin is being actively developed
+it can be cloned to `lib-extra`, e.g. `lib-extra/plugin-bar-dev`
+then it can be tested with commands below:
+
+```bash
+./rebar3 eunit --dir lib-extra/plugin-bar-dev
+./rebar3 ct --dir lib-extra/plugin-bar-dev
+```
diff --git a/lib-extra/plugins b/lib-extra/plugins
index 03a360fd9..0f3177b9e 100644
--- a/lib-extra/plugins
+++ b/lib-extra/plugins
@@ -1,5 +1,4 @@
 {erlang_plugins,
-  [
-  {emqx_plugin_template, {git, "https://github.com/emqx/emqx-plugin-template", {branch, "master"}}}
+  [ {emqx_plugin_template, {git, "https://github.com/emqx/emqx-plugin-template", {branch, "master"}}}
   ]
 }.