github-mirrors/logstash
1
0
Fork 0
mirror of https://github.com/elastic/logstash.git synced 2025-04-24 14:47:19 -04:00
Code Issues Projects Releases Packages Wiki Activity

Changes file hierarchy for Contributing to Logstash

Browse source 
Fixes #3708
This commit is contained in:
Paul Echeverri 2015-08-12 12:46:58 -07:00 • committed by Jordan Sissel
parent 73a38043fa
commit f6444ef962
2 changed files with 38 additions and 38 deletions
Download patch file Download diff file Expand all files Collapse all files

6
docs/asciidoc/static/contributing-to-logstash.asciidoc
View file

@ -1,5 +1,5 @@
[[contributing-to-logstash]]
=== Contributing to Logstash
== Contributing to Logstash
Before version 1.5, Logstash included all plugins in each release. This made it
easy to make use of any plugin, but it complicated plugin development--a new
@ -8,7 +8,7 @@ release of Logstash became necessary if a plugin needed patching. Since version
input, codec, filter, or output plugins to Logstash much more easily!
[float]
==== Adding plugins
=== Adding plugins
Since plugins can now be developed and deployed independently of the Logstash
core, there are documents which guide you through the process of coding and
@ -20,7 +20,7 @@ deploying your own plugins:
* http://www.elasticsearch.org/guide/en/logstash/current/_how_to_write_a_logstash_output_plugin.html[How to write a Logstash output plugin]
[float]
==== Extending Logstash core
=== Extending Logstash core
We also welcome contributions and bug fixes to the Logstash core feature set.

70
docs/asciidoc/static/include/pluginbody.asciidoc
View file

@ -1,6 +1,6 @@
pass::[<?edit_url https://github.com/elastic/logstash/edit/master/docs/asciidoc/static/include/pluginbody.asciidoc ?>]
==== How to write a Logstash {plugintype} plugin
=== How to write a Logstash {plugintype} plugin
To develop a new {plugintype} for Logstash, you build a self-contained Ruby gem
whose source code lives in its own GitHub repository. The Ruby gem can then be
@ -17,7 +17,7 @@ versions, plugins were part of the core Logstash distribution.
{getstarted}
===== Create a GitHub repo for your new plugin
==== Create a GitHub repo for your new plugin
Each Logstash plugin lives in its own GitHub repository. To create a new repository for your plugin:
. Log in to GitHub.
@ -29,7 +29,7 @@ Each Logstash plugin lives in its own GitHub repository. To create a new reposit
** **Initialize this repository with a README** -- enables you to immediately clone the repository to your computer.
. Click **Create Repository**.
===== Copy the {plugintype} code
==== Copy the {plugintype} code
Build your local repository:
@ -88,7 +88,7 @@ For more information about the Ruby gem file structure and an excellent
walkthrough of the Ruby gem creation process, see
http://timelessrepo.com/making-ruby-gems
===== See what your plugin looks like
==== See what your plugin looks like
Before we dive into the details, open up the plugin file in your favorite text editor
and take a look.
@ -287,11 +287,11 @@ end # class LogStash::{pluginclass}::{pluginnamecap}
----------------------------------
endif::receive_method[]
===== Coding {plugintype} plugins
==== Coding {plugintype} plugins
Now let's take a line-by-line look at the example plugin.
===== `encoding`
==== `encoding`
It seems like a small thing, but remember to specify the encoding at the
beginning of your plugin code:
@ -304,7 +304,7 @@ beginning of your plugin code:
Logstash depends on things being in UTF-8, so we put this here to tell the Ruby
interpreter that we’re going to be using the UTF-8 encoding.
===== `require` Statements
==== `require` Statements
Logstash {plugintype} plugins require parent classes defined in
+logstash/pass:attributes[{plugintype}]s/base+ and logstash/namespace:
@ -319,11 +319,11 @@ require "logstash/namespace"
Of course, the plugin you build may depend on other code, or even gems. Just put
them here along with these Logstash dependencies.
===== Plugin Body
==== Plugin Body
Let's go through the various elements of the plugin itself.
===== Inline Documentation
==== Inline Documentation
Logstash provides infrastructure to automatically generate documentation for
plugins. We use the asciidoc format to write documentation so _any_ comments in
the source code will be first converted into asciidoc and then into html.
@ -367,7 +367,7 @@ match => {
TIP: For more asciidoc formatting tips, see the excellent reference at
https://github.com/elastic/docs#asciidoc-guide
===== `class` Declaration
==== `class` Declaration
The {plugintype} plugin class should be a subclass of
+LogStash::pass:attributes[{pluginclass}]::Base+:
@ -384,7 +384,7 @@ The class name should closely mirror the plugin name, for example:
LogStash::{pluginclass}::{pluginnamecap}
----
===== `config_name`
==== `config_name`
[source,ruby]
[subs="attributes"]
----------------------------------
@ -436,7 +436,7 @@ output {
endif::blockinput[]
endif::encode_method[]
===== Configuration Parameters
==== Configuration Parameters
[source,ruby]
----------------------------------
config :variable_name, :validate => :variable_type, :default => "Default value", :required => boolean, :deprecated => boolean
@ -458,7 +458,7 @@ will become a valid boolean in the config. This coercion works for the
`false`)
* `:deprecated` - informational (also a Boolean `true` or `false`)
===== Plugin Methods
==== Plugin Methods
{methodheader}
@ -467,7 +467,7 @@ will become a valid boolean in the config. This coercion works for the
// /////////////////////////////////////////////////////////////////////////////
ifdef::register_method[]
===== `register` Method
==== `register` Method
[source,ruby]
[subs="attributes"]
----------------------------------
@ -496,7 +496,7 @@ endif::register_method[]
ifdef::filter_method[]
ifndef::blockfilter[]
===== `filter` Method
==== `filter` Method
[source,ruby]
[subs="attributes"]
@ -539,7 +539,7 @@ endif::filter_method[]
ifdef::decode_method[]
ifndef::blockcodec[]
===== `decode` Method
==== `decode` Method
[source,ruby]
[subs="attributes"]
@ -569,7 +569,7 @@ endif::decode_method[]
ifdef::encode_method[]
ifndef::blockcodec[]
===== `encode` Method
==== `encode` Method
[source,ruby]
[subs="attributes"]
@ -596,7 +596,7 @@ endif::encode_method[]
ifdef::run_method[]
ifndef::blockinput[]
===== `run` Method
==== `run` Method
The {pluginname} input plugin has the following `run` Method:
@ -684,7 +684,7 @@ endif::run_method[]
// /////////////////////////////////////////////////////////////////////////////
ifdef::receive_method[]
===== `receive` Method
==== `receive` Method
[source,ruby]
[subs="attributes"]
@ -749,7 +749,7 @@ endif::receive_method[]
At this point in the process you have coded your plugin and are ready to build
a Ruby Gem from it. The following steps will help you complete the process.
===== External dependencies
==== External dependencies
A `require` statement in Ruby is used to include necessary code. In some cases
your plugin may require additional files. For example, the collectd plugin
@ -788,7 +788,7 @@ will be discussed further in the testing section of this document.
Another kind of external dependency is on jar files. This will be described
in the "Add a `gemspec` file" section.
===== Add a Gemfile
==== Add a Gemfile
Gemfiles allow Ruby's Bundler to maintain the dependencies for your plugin.
Currently, all we'll need is the Logstash gem, for testing, but if you require
@ -804,7 +804,7 @@ gemspec
gem "logstash", :github => "elastic/logstash", :branch => "{branch}"
----------------------------------
===== Add a `gemspec` file
==== Add a `gemspec` file
Gemspecs define the Ruby gem which will be built and contain your plugin.
TIP: More information can be found on the
@ -875,7 +875,7 @@ This plugin should work but would benefit from use by folks like you. Please let
You will no longer see a message indicating potential code immaturity when a
plugin reaches version 1.0.0
===== Runtime & Development Dependencies
==== Runtime & Development Dependencies
At the bottom of the `gemspec` file is a section with a comment:
`Gem dependencies`. This is where any other needed gems must be mentioned. If
@ -903,7 +903,7 @@ and less than version 2.0 `'< 2.0.0'`.
IMPORTANT: All plugins have a runtime dependency on the `logstash` core gem, and
a development dependency on `logstash-devutils`.
===== Jar dependencies
==== Jar dependencies
In some cases, such as the
https://github.com/logstash-plugins/logstash-output-elasticsearch/blob/master/logstash-output-elasticsearch.gemspec#L22-L23[Elasticsearch output plugin],
@ -921,7 +921,7 @@ added in the gemspec file in this manner:
With these both defined, the install process will search for the required jar
file at http://mvnrepository.com and download the specified version.
===== Add Tests
==== Add Tests
Logstash loves tests. Lots of tests. If you're using your new {plugintype}
plugin in a production environment, you'll want to have some tests to ensure you
@ -934,7 +934,7 @@ For help learning about tests and testing, look in the
+spec/pass:attributes[{plugintype}]s/+ directory of several other similar
plugins.
===== Clone and test!
==== Clone and test!
Now let's start with a fresh clone of the plugin, build it and run the tests.
@ -978,11 +978,11 @@ Finished in 0.034 seconds
Hooray! You're almost there! (Unless you saw failures... you should fix those
first).
===== Building and Testing
==== Building and Testing
Now you're ready to build your (well-tested) plugin into a Ruby gem.
===== Build
==== Build
You already have all the necessary ingredients, so let's go ahead and run the
build command:
@ -1001,7 +1001,7 @@ logstash-{plugintype}-mypluginname-0.1.0.gem
The `s.version` number from your gemspec file will provide the gem version, in
this case, `0.1.0`.
===== Test installation
==== Test installation
You should test install your plugin into a clean installation of Logstash.
Download the latest version from the
@ -1182,13 +1182,13 @@ endif::receive_method[]
Congratulations! You've built, deployed and successfully run a Logstash
{plugintype}.
===== Submitting your plugin to http://rubygems.org[RubyGems.org] and https://github.com/logstash-plugins[logstash-plugins]
==== Submitting your plugin to http://rubygems.org[RubyGems.org] and https://github.com/logstash-plugins[logstash-plugins]
Logstash uses http://rubygems.org[RubyGems.org] as its repository for all plugin
artifacts. Once you have developed your new plugin, you can make it available to
Logstash users by simply publishing it to RubyGems.org.
===== Licensing
==== Licensing
Logstash and all its plugins are licensed under
https://github.com/elasticsearch/logstash/blob/master/LICENSE[Apache License, version 2 ("ALv2")].
If you make your plugin publicly available via http://rubygems.org[RubyGems.org],
@ -1196,7 +1196,7 @@ please make sure to have this line in your gemspec:
* `s.licenses = ['Apache License (2.0)']`
===== Publishing to http://rubygems.org[RubyGems.org]
==== Publishing to http://rubygems.org[RubyGems.org]
To begin, you’ll need an account on RubyGems.org
@ -1251,13 +1251,13 @@ by running:
bin/plugin install logstash-{plugintype}-mypluginname
----------------------------------
===== Contributing your source code to https://github.com/logstash-plugins[logstash-plugins]
==== Contributing your source code to https://github.com/logstash-plugins[logstash-plugins]
It is not required to contribute your source code to
https://github.com/logstash-plugins[logstash-plugins] github organization, but
we always welcome new plugins!
===== Benefits
==== Benefits
Some of the many benefits of having your plugin in the logstash-plugins
repository are:
@ -1271,7 +1271,7 @@ tested against current and future releases of Logstash. As a result, users will
have the assurance that if incompatibilities arise, they will be quickly
discovered and corrected.
===== Acceptance Guidelines
==== Acceptance Guidelines
* **Code Review** Your plugin must be reviewed by members of the community for
coherence, quality, readability, stability and security.