adding plugin status functionality

docs/docgen.rb

@@ -23,6 +23,7 @@ class LogStashConfigDocGenerator
       /^ *class.*< *LogStash::(Outputs|Filters|Inputs)::Base/ => \
         lambda { |m| set_class_description },
       /^ *config +[^=].*/ => lambda { |m| add_config(m[0]) },
+      /^ *plugin_status .*/ => lambda { |m| set_plugin_status(m[0]) },
       /^ *config_name .*/ => lambda { |m| set_config_name(m[0]) },
       /^ *flag[( ].*/ => lambda { |m| add_flag(m[0]) },
       /^ *(class|def|module) / => lambda { |m| clear_comments },
@@ -96,6 +97,11 @@ class LogStashConfigDocGenerator
     @name = name
   end # def set_config_name
 
+  def set_plugin_status(code)
+    status = eval(code)
+    @plugin_status = status
+  end
+
   # pretend to be the config DSL and just get the name
   def config(name, opts={})
     return name, opts
@@ -113,6 +119,11 @@ class LogStashConfigDocGenerator
     return name
   end # def config_name
 
+  # pretend to be the config dsl's 'plugin_status' method
+  def plugin_status(status)
+    return status
+  end # def plugin_status
+
   def clear_comments
     @comments.clear
   end # def clear_comments
@@ -126,6 +137,7 @@ class LogStashConfigDocGenerator
     @comments = []
     @settings = {}
     @class_description = ""
+    @plugin_status = ""
 
     # parse base first
     parse(File.new(File.join(File.dirname(file), "base.rb"), "r").read)

docs/docs.html.erb

@@ -3,6 +3,7 @@ title: logstash docs for <%= section %>s/<%= name %>
 layout: content_right
 ---
 <h2><%= name %></h2>
+<h3>Status: <a href="plugin-status"><%= @plugin_status %></a></h3>
 
 <%= description %>
 

docs/plugin-status.md

@@ -0,0 +1,23 @@
+---
+title: Plugin Status - logstash
+layout: content_right
+---
+# Plugin Status
+
+Plugins (inputs/outputs/filters) have a status in logstash. This is to provide an indicator to the end-user as to the 'state' of the plugin.
+
+Terminology is still being worked out but there are three general states - experimental, unstable, stable.
+
+The desire here is to allow people to quickly iterate on possible new plugins while conveying to the end-user a set of expectations about that plugin. This allows you to make more informed decisions about when and where to use the functionality provided by the new plugin.
+
+## Experimental
+When a plugin is in the `experimental` state, it is essentially untested. This does not mean that it does not have any associated unit tests. This applies more to in-the-wild usage. Most new plugins will probably fit in this category. There is a chance that experimental plugins may be removed at some point. It is possible that an experimental plugin will be broken mid-release.
+
+## Unstable
+Unstable plugins are plugins that are in the process of being stabalized into a final form. Unstable plugins will have a bit more wide-spread usage in the community. The API for these plugins has stabilized and is unlikely to change mid-release.
+
+## Stable
+Stable plugins are plugins that you can comfortably rely on in production.
+
+# A note about output plugins
+It's worth reminding users that `output` plugins are currently blocking. If any output plugin fails, all output plugins are blocked. Please keep this in mind when using experimental output plugins as it could cause unintended side-effects.

lib/logstash/config/mixin.rb

@@ -99,6 +99,11 @@ module LogStash::Config::Mixin
       return @config_name
     end
 
+    def plugin_status(status=nil)
+      @plugin_status = status if !status.nil?
+      return @plugin_status
+    end
+
     # Define a new configuration setting
     def config(name, opts={})
       @config ||= Hash.new

lib/logstash/filters/base.rb

@@ -8,6 +8,8 @@ class LogStash::Filters::Base < LogStash::Plugin
 
   config_name "filter"
 
+  plugin_status "unstable"
+
   # The type to act on. If a type is given, then this filter will only
   # act on messages with the same type. See any input plugin's "type"
   # attribute for more.

lib/logstash/inputs/base.rb

@@ -9,6 +9,8 @@ class LogStash::Inputs::Base < LogStash::Plugin
   include LogStash::Config::Mixin
   config_name "input"
 
+  plugin_status "unstable"
+
   # Label this input with a type.
   # Types are used mainly for filter activation.
   #

lib/logstash/outputs/base.rb

@@ -11,6 +11,8 @@ class LogStash::Outputs::Base < LogStash::Plugin
 
   config_name "output"
 
+  plugin_status "unstable"
+
   # The type to act on. If a type is given, then this output will only
   # act on messages with the same type. See any input plugin's "type"
   # attribute for more.