new: doc: add doc on root level ``type`` key of ``metadata.yml``

README.org

@@ -76,3 +76,66 @@ TBD
 Most tools should check the =CHARM_STORE= bash environment variable
 that should be the path to reach the root of this repository. If not
 defined, most tools will look in =/srv/charm-store= by default.
+
+* Specs
+
+** charm type
+
+Not all charm are intended to bring up services as having a container
+always running and listening.
+
+In ~metadata.yml~, the root level ~type~ can be one of:
+
+- ~service~ (default)
+
+  If not specified, this is the default. A charm brings up a service.
+  It is meant to be *always running*. For instance, ~apache~, ~mysql~,
+ ~postgres~ are services.
+
+  They usually open ports and are listening to provide their service,
+  or carry background listening of other ressources (like checking
+  time and sending scheduling command for the ~cron~ services), and or
+  use files to trigger or report on their activity.
+
+  It will have an entry in the final ~docker-compose.yml~, and thus, a
+  container will run and stay in memory and have a ~restart:
+  unless-stopped~ policy. They use CPU and memory ressources.
+
+- ~run-once~
+
+  The entry is meant to describe *a command that run once*,
+  it will be called by a service and *will exit after execution*.
+
+  For instance, ~logrotate~, ~rsync-backup~, or ~letsencrypt~ are
+  of type ~run-once~.
+
+  They are meant to be run by service for specific events. They
+  usually will use relations to ensure they are called at specific
+  moment by service...
+
+  A command does not have an automatic ~restart~ policy as services
+  have.
+
+  They use CPU and memory ressources only when run and gives them back
+  once finished.
+
+- ~stub~
+
+  The entry describes an entity that will *not be run at all*. It is
+  used to hold information in the ~compose.yml~ and often to *stand
+  for* a real service managed outside of ~compose.yml~ (on an other
+  host or on a different managing system, like a local installation or
+  LXC, virtualbox, ...).
+
+  For instance, ~stmp-stub~ can be used to stand for an external ~smtp~.
+
+  It is through their relation that they shine as they can provide
+  similar interface than actual services would have
+  provided. ~smtp-stub~ is a ~smtp-server~ provider and other charm
+  can connect to it.
+
+  They usually implement relation hooks, and are providers.
+
+  No entry will be created in the final ~docker-compose.yml~.
+
+  They use no CPU or memory ressources at all.