Define Plugin Status types

* Introduction of a tiered approach to plugin maturity * Added definitions where these terms will be important to understand
intelsdi-x · Jan 25, 2017 · fc34b69 · fc34b69
1 parent f36d1aa
commit fc34b69
Show file tree

Hide file tree

Showing 4 changed files with 105 additions and 13 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -8,8 +8,15 @@ Snap is Apache 2.0 licensed and accepts contributions via GitHub. This document
 
 * [Reporting Security Issues](#reporting-security-issues)
 * [Reporting Issues or Feature Requests](#reporting-issues-or-feature-requests)
+   * [What is an RFC?](#what-is-an-rfc)
 * [Contributing Code](#contributing-code)
+   * [Commit Guidelines](#commit-guidelines)
+   * [Testing Guidelines](#testing-guidelines)
+   * [Pull Request Guidelines](#pull-request-guidelines)
+* [Submitting a Plugin](#submitting-a-plugin)
 * [Notes on GitHub Usage](#notes-on-github-usage)
+   * [TL;DR Labels](#tldr-labels)
+   * [Issue Labels](#issue-labels)
 
 ## Reporting Security Issues
 
@@ -82,17 +89,24 @@ Your pull request should be rebased against the current master branch. Please do
 the current master branch in with your topic branch, nor use the Update Branch button provided
 by GitHub on the pull request page.
 
+## Submitting a Plugin
+
+Sharing a new plugin is one of the most impressive ways to jump into the Snap community as a contributor. This process is as simple as adding your plugin information to the [list in plugis.yml](docs/plugin.yml). Read more about what is required of plugin authors in [Plugin Authoring](docs/PLUGIN_AUTHORING.md).
+
 ## Notes on GitHub Usage
+
 It's worth noting that we don't use all the native GitHub features for issue management. For instance, it's uncommon for us to assign issues to the developer who will address it. Here are notes on what we do use.
 
 ### TL;DR Labels
+
 We use a number of labels for context in the main framework of Snap. Plugin repository labels will keep it simple. If you want to contribute to Snap, here are the most helpful ones for you:
 
 1. **help-wanted** ([link](https://github.com/intelsdi-x/snap/labels/help-wanted)) - some specific issues maintainers would like help addressing
 2. **type/rfc** ([link](https://github.com/intelsdi-x/snap/labels/type%2Frfc)) - we need active feedback on *how best* to solve these issues
 3. **plugin-wishlist** ([link](https://github.com/intelsdi-x/snap/labels/plugin-wishlist)) - these are a great opportunity to write a plugin
 
 ### Issue Labels
+
 Snap maintainers have a set of labels we use to keep up with issues. They are separated into namespaces:
 
 * **type/** - the category of issue. All issues will have one or more

diff --git a/docs/GLOSSARY.md b/docs/GLOSSARY.md
@@ -12,6 +12,7 @@ Snap is simple in scope and it becomes more simple when you know the terminology
     * [Metric Namespace: Dynamic Element](#metric-dynamic-namespace-element)
     * [Metric Namespace: Static Element](#metric-static-namespace-element)
     * [Plugin](#plugin)
+    * [Plugin Status](#plugin-status)
     * [Plugin Type: Collector](#plugin-type-collector)
     * [Plugin Type: Processor](#plugin-type-processor)
     * [Plugin Type: Publisher](#plugin-type-publisher)
@@ -24,9 +25,9 @@ Snap is simple in scope and it becomes more simple when you know the terminology
     * [Tribe](#tribe)
     * [Workflow](#workflow)
     * [Workflow: Distributed](#workflow-distributed)
-    * [Workflow Manifest](#workflow-manifest) 
+    * [Workflow Manifest](#workflow-manifest)
 
-### Config: Global Config 
+### Config: Global Config
 * Values loaded at runtime of the daemon ([reference](SNAPTELD_CONFIGURATION.md))
 
 ### Config: Global Options
@@ -47,7 +48,7 @@ Snap is simple in scope and it becomes more simple when you know the terminology
 ### Metric: Namespace
 * Namespaces are a series of namespace elements that uniquely identify a metric in Snap ([reference](METRICS.md))
 
-#### Metric: Dynamic Namespace Element 
+#### Metric: Dynamic Namespace Element
 * An element of a metric whose value is set at runtime ([reference](METRICS.md))
 
 #### Metric: Static Namespace Element
@@ -56,19 +57,22 @@ Snap is simple in scope and it becomes more simple when you know the terminology
 ### Plugin
 * An independent [binary][binary] that is compatible with Snap (see [Plugin Lifecycle](PLUGIN_LIFECYCLE.md))
 
+### Plugin Status
+* An indicator of whether a plugin meets the maintainer's recommendations for best practices (see [Plugin Status](PLUGIN_STATUS.md))
+
 ### Plugin Type: Collector
 * Gathers data and presents as a dynamically-generated namespaced metric catalog ([reference](PLUGIN_AUTHORING.md#plugin-type))
 
-### Plugin Type: Processor 
+### Plugin Type: Processor
 * Extends or filters collected metrics ([reference](PLUGIN_AUTHORING.md#plugin-type))
 
 ### Plugin Type: Publisher
 * Persists metrics into a target endpoint ([reference](PLUGIN_AUTHORING.md#plugin-type))
 
-### Snap 
+### Snap
 * The project name, focused on the Snap daemon and the plugins that power its collection, processing and publishing of telemetry
 
-### Snap Telemetry 
+### Snap Telemetry
 * The full name of the Snap project, used mostly for easy searching (like snap-telemetry.io) or hashtag (#SnapTelemetry)
 
 ### 'snaptel'
@@ -80,19 +84,19 @@ Snap is simple in scope and it becomes more simple when you know the terminology
 ### Task
 * A job running within Snap, including the API version, schedule and workflow (all documented [here](TASKS.md))
 
-### Task Manifest 
+### Task Manifest
 * A file that includes the API version, schedule and workflow of a Task in a declarative form ([reference](TASKS.md#task-manifest))
 
 ### Tribe
 * The clustering feature of Snap, documented [here](TRIBE.md)
 
-### Workflow 
+### Workflow
 * The explicit map of how collectors, processors and publishers are used in Snap ([reference](TASKS.md#the-workflow))
 
 ### Workflow: Distributed
 * A workflow where one or more steps have a remote target specified ([reference](DISTRIBUTED_WORKFLOW_ARCHITECTURE.md))
 
-### Workflow Manifest 
+### Workflow Manifest
 * A file that describes only the workflow of a Task ([example at the bottom](SNAPTEL.md#load-and-unload-plugins-create-and-start-a-task))
 
 [binary]: https://www.quora.com/Whats-the-difference-between-an-installer-source-code-and-a-binary-package-when-installing-software
diff --git a/docs/PLUGIN_AUTHORING.md b/docs/PLUGIN_AUTHORING.md
@@ -3,7 +3,7 @@
 ### Table of Content
 
 * [Overview](#overview)
-  * [Plugin Library](#plugin-library)
+   * [Plugin Library](#plugin-library)
 * [Developing Plugins](#developing-plugins)
    * [Plugin Type](#plugin-type)
    * [Plugin Name](#plugin-name)
@@ -127,7 +127,7 @@ In the plugin repo root directory, the `metadata.yml` file provides Snap project
 * **description**: paragraph describing the plugin's purpose
 * **badge**: a list of [badges](https://shields.io/) to display
 * **ci**: a list of ci services running for this repo
-* **status**: one of the three statuses [described below](#plugin-status)
+* **status**: one of the four statuses [described below](#plugin-status)
 
 All metadata fields are optional, but recommended to help users discover your plugin. Please check out the file plugin's [metadata.yml](https://github.com/intelsdi-x/snap-plugin-publisher-file/blob/master/metadata.yml) file for a working example.
 
@@ -144,12 +144,19 @@ We provide a list of Snap plugins at [snap-telemetry.io](http://snap-telemetry.i
 
 ### Plugin Status
 
-While the Snap framework is hardened through tons of testing, **plugins mature at their own pace**. We want our community to share plugins early and update them often. We are defining categories of maturity of a plugin and will roll them out with the resolution of [#1322](https://github.com/intelsdi-x/snap/issues/1322).
+While the Snap framework is hardened through tons of testing, **plugins mature at their own pace**. We also want our community to share plugins early and update them often. To help both of these goals, we have tiers of maturity defined for plugins being added to the Plugin Catalog:
+* [**Supported**](#supported-plugins) - Created by a company with the intent of supporting customers
+* [**Approved**](#approved-plugins) - Vetted by Snap maintainers to meet our best practices for design
+* [**Experimental**](#experimental) - Early plugins ready for testing but not known to work as intended
+* [**Unlabeled**](#all-other-plugins-unlabeled) - Shared for reference or extension
+
+ Further details to these definitions are available in [Plugin Status](PLUGIN_STATUS.md).
 
 ### Documentation
 
-All plugins should include a README with the following information:
+We request that all plugins include a README with the following information:
 
+1. What It Does (and who it's for)
 1. Supported Platforms
 1. Known Issues
 1. Snap Version dependencies

diff --git a/docs/PLUGIN_STATUS.md b/docs/PLUGIN_STATUS.md
@@ -0,0 +1,67 @@
+# Plugin Status
+
+Not all plugins are designed with the same level of readiness in mind. To visualize that fact while also allowing everyone to share their work, we have introduced the concept of "tiers" of plugins. These tiers are communicated as statuses which will be visualized everywhere you see the [Plugin Catalog](PLUGIN_CATALOG.md).
+
+Note that plugins can and likely will be demoted if they fall significantly behind best practices of the project. I know that's vague, but it will have to do for this first version :grimacing:
+
+### What this is
+
+* A way to quickly see the highest quality plugins
+* A way to encourage contribution to existing plugins instead of forking
+
+### What this is not
+
+* Not a definition of the plugin version - that's done through `releases`
+* Not a contract of support - we do our best as maintainers of Snap, but make no promises
+
+## Plugin Status Matrix
+
+All plugins meet a set of minimum requirements to be included at its status level. Note that some earlier stage plugins *can* have other requirements implemented, but they *must* have all checkboxes to be in the next tier.
+
+| Requirements                   |     Unlabeled      |    Experimental    |      Approved      |     Supported      |
+|:-------------------------------|:------------------:|:------------------:|:------------------:|:------------------:|
+| No naming conflict             | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
+| Includes README.md             |                    | :white_check_mark: | :white_check_mark: | :white_check_mark: |
+| Active maintainers             |                    | :white_check_mark: | :white_check_mark: | :white_check_mark: |
+| Release includes binary        |                    |                    | :white_check_mark: | :white_check_mark: |
+| Known to compile               |                    |                    | :white_check_mark: | :white_check_mark: |
+| Known to load in Snap          |                    |                    | :white_check_mark: | :white_check_mark: |
+| Uses Snap plugin library       |                    |                    | :white_check_mark: | :white_check_mark: |
+| Reasonable test coverage       |                    |                    | :white_check_mark: | :white_check_mark: |
+| Includes example tasks         |                    |                    | :white_check_mark: | :white_check_mark: |
+| Includes dependency management |                    |                    | :white_check_mark: | :white_check_mark: |
+| Includes CI status             |                    |                    | :white_check_mark: | :white_check_mark: |
+| Includes license               |                    |                    | :white_check_mark: | :white_check_mark: |
+| Support provided by a company  |                    |                    |                    | :white_check_mark: |
+
+## Supported Plugins
+
+These are our premier plugins for the Snap telemetry framework and its users. These are designed to follow all of our recommended practices. Issues are also closely monitored by its supporting company ([read more about that here](#more-on-support-for-plugins)). While companies may support some plugins they contribute to Snap, not all contributions will meet the Supported standard.
+
+We prefer to not have other repositories that overlap with Supported plugins and suggest contributing to the existing version to help keep this list small and effective. Like all plugins, community contribution is welcome.
+
+
+## Approved Plugins
+
+These are primarily community-contributed plugins that meet or exceed the project's best practices. These plugins have been vetted by Snap maintainers as of the date listed in the Plugin Catalog. They are excellent references and are quite likely ready for use in your own Snap deployment.
+
+We prefer to not have other repositories that overlap with Approved plugins and suggest contributing to the existing version to help keep this list small and effective. Don't be shy about reaching out to existing plugin authors to see if you can help improve upon it.
+
+## Experimental
+
+These plugins are in development and are not yet complete, but are shared with the community for feedback and testing. They are shared with the community for feedback and testing. Think of this tier as an incubation phase that should move toward Approved or drop down to Unlabeled.
+
+We prefer to not have other repositories that overlap with Experimental plugins and suggest contributing to the existing version to help keep this list small and effective. Don't be shy about reaching out to existing plugin authors to see if you can help improve upon it.
+
+
+## All Other Plugins (Unlabeled)
+
+These are plugins in varying phases of completeness and are shared for reference. They do not necessarily follow best practices for plugin development. We welcome anyone forking these plugins and working toward Approved status.
+
+## Changing Tiers 
+
+If you find a plugin that should move between tiers (ex. from Unlabeled to Approved, Supported to Experimental or Approved to Experimental), open an issue to do so on the [main Snap repository](https://github.com/intelsdi-x/snap/issues). Please include any corresponding issues opened on the plugin repository as well. 
+
+## More On Support For Plugins
+
+Snap is an open source project originated and actively maintained by Intel with the goal of becoming a broad community standard for telemetry. We stand behind Supported plugins with the intention of making them part of your monitoring infrastructure. As other companies adopt Snap as their standard telemetry framework, they may also choose to support various plugins. We want to make sure you know which ones, and what companies, are here to support you.