Merge pull request #375 from kenhys/warn-plugin

1.0: add note about breaking functionality

Author: kenhys

deployment/plugin-management.md

@@ -14,6 +14,18 @@ fluent-gem install fluent-plugin-grep
 
 Ruby does not guarantee the C extension API compatibility between its major versions. If you update Fluentd's Ruby version, you should reinstall the plugins that depend on C extension.
 
+### Do not use unreliable plugins
+
+Any fluentd plugin can unknowingly break fluentd completely (and possibly break other plugins) by requiring some incompatible modules.
+
+There is no way to block this kind of situation. This is because the problem itself is derived from plug-in mechanism, and that's Lightweight Language.
+One solution is "Do not use unreliable plugins".
+
+Generally speaking, plug-in mechanism can break core functionality not only Fluentd but also in most other software.
+We shouldn't use unreliable plugins in any software.
+
+We recommend to send feedback to plugin owner if you faced such a fault in plugins.
+
 ### If Using `td-agent`, Use `/usr/sbin/td-agent-gem`
 
 If you are using `td-agent`, make sure that you use `td-agent-gem` command to install gems for it. Otherwise, you won't be able to find the **installed** plugins.

plugin-development/README.md

@@ -51,6 +51,15 @@ It is recommended to use the new v1 plugin API for writing new plugins.
 
 If you have a problem with any existing plugins or a new feature idea, sending a patch is better. If the plugin author is non-active, try to become its new plugin maintainer first. Forking a plugin and release its alternative version, e.g. `fluent-plugin-xxx-alt` is considered the last option.
 
+### Be careful not breaking Fluentd's core functionality
+
+Any fluentd plugin can unknowingly break fluentd completely (and possibly break other plugins) by requiring some incompatible modules.
+
+One typical example is reloading `yajl/json_gem` from plugin. (`yajl/json_gem` compatibility layer is problematic, not for `yajl` itself)
+It breaks a functionality to parse Fluentd's configuration completely.
+
+Fluentd's plug-in mechanism has a merit to extend functionality, but plugin developer must be careful a possibility of breaking it.
+
 ## Writing Plugins
 
 To create a plugin as a Ruby script \(to put it in `/etc/fluent/plugin/` directory\), create a `<TYPE>_<NAME>.rb` file in any editor/IDE of your choice.