Doc: Update contributing steps and guidelines (#12895)

Backports #12879 to 7.x

docs/index.asciidoc

@@ -238,31 +238,35 @@ include::static/codec.asciidoc[]
 include::static/filter.asciidoc[]
 include::static/output.asciidoc[]
 
-// Plugin doc guidelines
-
-:edit_url: https://github.com/elastic/logstash/edit/{branch}/docs/static/doc-for-plugin.asciidoc
-include::static/doc-for-plugin.asciidoc[]
-
-// Contributing a Patch to a Logstash Plugin
-
-:edit_url: https://github.com/elastic/logstash/edit/{branch}/docs/static/contributing-patch.asciidoc
-include::static/contributing-patch.asciidoc[]
-
 // Logstash Community Maintainer Guide
 
-:edit_url: https://github.com/elastic/logstash/edit/{branch}/docs/static/maintainer-guide.asciidoc
+:edit_url!: 
 include::static/maintainer-guide.asciidoc[]
 
 // A space is necessary here ^^^
 
+// Plugin doc guidelines
+
+:edit_url: 
+include::static/doc-for-plugin.asciidoc[]
+
 // Submitting a Plugin
 
-:edit_url: https://github.com/elastic/logstash/edit/{branch}/docs/static/submitting-a-plugin.asciidoc
+:edit_url!: 
 include::static/submitting-a-plugin.asciidoc[] 
 
+:edit_url!:
+include::static/listing-a-plugin.asciidoc[]
+
+:edit_url!: 
+include::static/contributing-patch.asciidoc[]
+
+:edit_url!:
+include::static/contribute-core.asciidoc[]
+
 // Contributing to Logstash - JAVA EDITION
 
-:edit_url: https://github.com/elastic/logstash/edit/{branch}/docs/static/contributing-java-plugin.asciidoc
+:edit_url: 
 include::static/contributing-java-plugin.asciidoc[]
 
 // Glossary of Terms

docs/static/contrib-acceptance.asciidoc

@@ -0,0 +1,19 @@
+[discrete]
+[[plugin-acceptance]]
+==== Acceptance guidelines
+
+Start with the end in mind. 
+These guidelines and best practices can help you build a better plugin, even if you choose not to share it with the world.
+
+* **Consistency.** Your plugin must be consistent in quality and naming conventions used by other plugins. 
+The plugin name must be unique and in this format: `logstash-plugintype-pluginname`. 
+If the plugin name is more than one word, separate words after plugin type with underscores. 
+Example: _logstash-output-elastic_app_search_
+* **Documentation.** Documentation is a required component of your plugin. 
+If we list your plugin in the Logstash Reference, we point to your documentation--a readme.md, docs/index.asciidoc, or both--in your plugin repo.
+* **Code Review.** Your plugin must be reviewed by members of the community for coherence, quality, readability, stability and security.
+* **Tests.** Your plugin must contain tests to be accepted. You can refer to http://betterspecs.org/ for examples. 
+** Step 1. Enable travis on your account
+** Step 2. Import our standard travis.yml https://github.com/logstash-plugins/.ci/blob/1.x/travis/travis.yml, as shown in the
+https://github.com/logstash-plugins/logstash-filter-fingerprint/blob/master/.travis.yml[fingerprint filter example].
+** Step 3. Have specs in the spec folder.

docs/static/contribute-core.asciidoc

@@ -0,0 +1,10 @@
+[[contribute-to-core]]
+=== Extending Logstash core
+
+We also welcome contributions and bug fixes to the Logstash core feature set.
+
+Please read through our
+https://github.com/elastic/logstash/blob/master/CONTRIBUTING.md[contribution]
+guide, and the Logstash
+https://github.com/elastic/logstash/blob/master/README.md[readme]
+document.

docs/static/contributing-java-plugin.asciidoc

@@ -5,8 +5,7 @@ Now you can write your own Java plugin for use with {ls}.
 We have provided instructions and GitHub examples to give
 you a head start. 
 
-Native support for Java plugins in {ls} consists of several components
+Native support for Java plugins in {ls} consists of several components:
-including:
 
 * Extensions to the Java execution engine to support running Java plugins in
 Logstash pipelines
@@ -17,7 +16,7 @@ implementations of API interfaces outside that package. The implementation of
 classes outside of the API package may change at any time.
 * Tooling to automate the packaging and deployment of Java plugins in Logstash.
 
-[float]
+[discrete]
 === Process overview
 Here are the steps:
 

docs/static/contributing-patch.asciidoc

@@ -1,24 +1,26 @@
 [[contributing-patch-plugin]]
-=== Contributing a Patch to a Logstash Plugin
+=== Contributing a patch to a Logstash plugin
 
 This section discusses the information you need to know to successfully contribute a patch to a Logstash plugin.
 
-Each plugin defines its own configuration options. These control the behaviour of the plugin to some degree. Configuration 
+Each plugin defines its own configuration options. These control the behavior of the plugin to some degree. 
-option definitions commonly include:
+Configuration option definitions commonly include:
 
 * Data validation
-* The default value
+* Default value
 * Any required flags
 
 Plugins are subclasses of a Logstash base class. A plugin's base class defines common configuration and methods.
 
-==== Input Plugins
+[[contrib-patch-input]]
+==== Input plugins
 
 Input plugins ingest data from an external source. Input plugins are always associated with a codec. An input plugin 
 always has an associated codec plugin. Input and codec plugins operate in conjunction to create a Logstash event and add 
 that event to the processing queue. An input codec is a subclass of the `LogStash::Inputs::Base` class.
 
-.Input API
+[[input-api]]
+===== Input API
 [horizontal]
 `#register() -> nil`:: Required. This API sets up resources for the plugin, typically the connection to the 
 external source.
@@ -27,12 +29,14 @@ errors inside the loop. Pushes any created events to the queue object specified
 receive batched data to minimize the external call overhead.
 `#stop() -> nil`:: Optional. Stops external connections and cleans up.
 
-==== Codec Plugins
+[[contrib-patch-codec]]
+==== Codec plugins
 
 Codec plugins decode input data that has a specific structure, such as JSON input data. A codec plugin is a subclass of 
 `LogStash::Codecs::Base`.
 
-.Codec API
+[[codec-api]]
+===== Codec API
 [horizontal]
 `#register() -> nil`:: Identical to the API of the same name for input plugins.
 `#decode(data){|event| block} -> nil`:: Must be implemented. Used to create an Event from the raw data given in the method 
@@ -41,22 +45,26 @@ argument. Must handle errors. The caller must provide a Ruby block. The block is
 errors. This method calls a block that was previously stored as @on_event with two arguments: the original event and the 
 data object.
 
-==== Filter Plugins
+[[contrib-patch-filter]]
+==== Filter plugins
 
 A mechanism to change, mutate or merge one or more Events. A filter plugin is a subclass of the `LogStash::Filters::Base` 
 class.
 
-.Filter API
+[[filter-api]]
+===== Filter API
 [horizontal]
 `#register() -> nil`:: Identical to the API of the same name for input plugins.
 `#filter(event) -> nil`:: Required. May handle errors. Used to apply a mutation function to the given event.
 
-==== Output Plugins
+[[contrib-patch-output]]
+==== Output plugins
 
 A mechanism to send an event to an external destination. This process may require serialization. An output plugin is a 
 subclass of the `LogStash::Outputs::Base` class.
 
-.Output API
+[[output-api]]
+===== Output API
 [horizontal]
 `#register() -> nil`:: Identical to the API of the same name for input plugins.
 `#receive(event) -> nil`:: Required. Must handle errors. Used to prepare the given event for transmission to 
@@ -72,23 +80,27 @@ The <<community-maintainer,Community Maintainer Guide>> explains, in more detail
 merged and published.  The Community Maintainer Guide also details the roles that contributors and maintainers are 
 expected to perform.
 
-==== Testing Methodologies
+[[test-methods]]
+==== Testing methodologies
 
-===== Test Driven Development
+[[tdd]]
+===== Test driven development
 
-Test Driven Development, colloquially known as TDD, describes a methodology for using tests to guide evolution of source
+Test driven development (TDD) describes a methodology for using tests to guide evolution of source code. 
-code. For our purposes, we are only going to use a part of it, that is, before writing the fix - we create tests that 
+For our purposes, we are use only a part of it.
-illustrate the bug by failing. We stop when we have written enough code to make the tests pass and submit the fix and 
+Before writing the fix, we create tests that illustrate the bug by failing. 
-tests as a patch. It is not necessary to write the tests before the fix, but it is very easy to write a passing test 
+We stop when we have written enough code to make the tests pass and submit the fix and tests as a patch. 
+It is not necessary to write the tests before the fix, but it is very easy to write a passing test 
 afterwards that may not actually verify that the fault is really fixed especially if the fault can be triggered via 
 multiple execution paths or varying input data.
 
-===== The RSpec Framework
+[[rspec]]
+===== RSpec framework
 
 Logstash uses Rspec, a Ruby testing framework, to define and run the test suite. What follows is a summary of various 
 sources.
 
-. Rspec Example
+.Rspec Example
 [source,ruby]
  2 require "logstash/devutils/rspec/spec_helper"
  3 require "logstash/plugin"
@@ -220,6 +232,7 @@ eql(object) -> matcher instance
 In RSpec, a matcher is an object generated by the equivalent method call (be, eq) that will be used to evaluate the 
 expected against the actual values.
 
+[[all-together]]
 ==== Putting it all together
 
 This example fixes an https://github.com/logstash-plugins/logstash-output-zeromq/issues/9[issue] in the ZeroMQ output 

docs/static/contributing-to-logstash.asciidoc

@@ -3,25 +3,32 @@
 
 You can add your own input, codec, filter, or output plugins to Logstash. 
 
-[float]
+include::contrib-acceptance.asciidoc[]
-=== Adding plugins
 
-Plugins can be developed and deployed independently of the Logstash
+[discrete]
-core. Here are some documents to guide you through the process of coding and
+[[add-plugin]]
-deploying your own plugin:
+=== Add a plugin
 
-* <<plugin-generator,Generating a New Plugin>>
+Plugins can be developed and deployed independently of the Logstash core. 
-* <<input-new-plugin,How to write a Logstash input plugin>>
+Here are some documents to guide you through the process of coding, deploying, and sharing your plugin:
-* <<codec-new-plugin,How to write a Logstash codec plugin>>
-* <<filter-new-plugin,How to write a Logstash filter plugin>>
-* <<output-new-plugin,How to write a Logstash output plugin>>
-* <<plugin-doc,Documenting your plugin>>
-* <<contributing-patch-plugin,Contributing a Patch to a Logstash Plugin>>
-* <<community-maintainer,Community Maintainer's Guide>>
-* <<submitting-plugin,Submitting a Plugin>>
 
-[float]
+* Write a new plugin 
-==== Plugin Shutdown APIs
+** <<input-new-plugin>>
+** <<codec-new-plugin>>
+** <<filter-new-plugin>>
+** <<output-new-plugin>>
+** <<community-maintainer,Community Maintainer's Guide>>
+* <<plugin-doc>>
+* <<publish-plugin>>
+* <<plugin-listing>>
+
+* Contribute a patch
+** <<contributing-patch-plugin>>
+** <<contribute-to-core>>
+
+[discrete]
+[[shutdown-apis]]
+===== Plugin Shutdown APIs
 
 You have three options for shutting down a plugin: `stop`, `stop?`, and `close`.
 
@@ -35,13 +42,3 @@ Plugin Base class.
 
 Sample code for the plugin shutdown APIs is https://github.com/logstash-plugins/logstash-input-example/blob/master/lib/logstash/inputs/example.rb[available].
 
-[float]
-=== Extending Logstash core
-
-We also welcome contributions and bug fixes to the Logstash core feature set.
-
-Please read through our
-https://github.com/elastic/logstash/blob/master/CONTRIBUTING.md[contribution]
-guide, and the Logstash
-https://github.com/elastic/logstash/blob/master/README.md[readme]
-document.

docs/static/doc-for-plugin.asciidoc

@@ -1,16 +1,29 @@
 [[plugin-doc]]
-=== Documenting your plugin
+=== Document your plugin
 
+Documentation is a required component of your plugin.
 Quality documentation with good examples contributes to the adoption of your plugin.
 
 The documentation that you write for your plugin will be generated and published
 in the {logstash-ref}/index.html[Logstash Reference] and the
 {lsplugindocs}[Logstash Versioned Plugin Reference].
 
+.Plugin listing in {ls} Reference
+[NOTE]
+=====
+We may list your plugin in the {logstash-ref}/index.html[Logstash Reference] if
+it meets our <<plugin-acceptance,requirements and quality standards>>. 
+When we list your plugin, we point to _your_ documentation--a readme.md, docs/index.asciidoc, or both--in your plugin repo.
+For more info on this option, see <<plugin-listing>>. 
+===== 
+
+The following sections contain guidelines for documenting plugins hosted in
+the Github https://github.com/logstash-plugins/[logstash-plugins] organization. 
+
 [[plugin-doc-file]]
 ==== Documentation file
 
-Documentation is a required component of your plugin.
+Documentation belongs in a single file called 'docs/index.asciidoc'.
 It belongs in a single file called 'docs/index.asciidoc'.
 The <<plugin-generator,plugin generation utility>> creates a starter file for you.  
 
@@ -23,7 +36,7 @@ is built. Unique heading IDs are required to avoid duplication over multiple ver
 
 *Example*
 
-Don't hardcode a heading ID like this: `[[config_models]]`
+Don't hardcode a plugin heading ID like this: `[[config_models]]`
 
 Instead, use variables to define it:
 
@@ -37,7 +50,6 @@ If you hardcode an ID, the {lsplugindocs}[Logstash Versioned Plugin Reference]
 builds correctly the first time. The second time the doc build runs, the ID
 is flagged as a duplicate, and the build fails.
 
-
 [[link-format]]
 ==== Link formats
 
@@ -65,7 +77,6 @@ Points to this heading in the same file:
 ==== Configuration models
 ----------------------------------
 
-
 ===== Link to content in the Logstash Reference Guide
 
 Use external link syntax for links that point to documentation for other plugins or content in the Logstash Reference Guide.
@@ -85,7 +96,6 @@ Use external link syntax for links that point to documentation for other plugins
 
 If you don't specify link text, the URL is used as the link text.
 
-
 *Examples*
 
 If you want your link to display as {logstash-ref}/getting-started-with-logstash.html, use this format:
@@ -94,14 +104,12 @@ If you want your link to display as {logstash-ref}/getting-started-with-logstash
 {logstash-ref}/getting-started-with-logstash.html
 -----
 
-
 If you want your link to display as {logstash-ref}/getting-started-with-logstash.html[Getting Started with Logstash], use this format:
 [source,txt]
 -----
 {logstash-ref}/getting-started-with-logstash.html[Getting Started with Logstash]
 -----
 
-
 ===== Link to data type descriptions
 
 We make an exception for links that point to data type descriptions,
@@ -109,7 +117,6 @@ such as `<<boolean,boolean>>`, because they are used so frequently.
 We have a cleanup step in the conversion script that converts the links to the
 correct syntax. 
 
-
 [[format-code]]
 ==== Code samples
 

docs/static/include/pluginbody.asciidoc

@@ -2,7 +2,7 @@
 
 === How to write a Logstash {plugintype} plugin
 
-To develop a new {plugintype} for Logstash, you build a self-contained Ruby gem
+To develop a new {plugintype} for Logstash, build a self-contained Ruby gem
 whose source code lives in its own GitHub repository. The Ruby gem can then be
 hosted and shared on RubyGems.org. You can use the example {plugintype}
 implementation as a starting point. (If you're unfamiliar with
@@ -27,7 +27,7 @@ Each Logstash plugin lives in its own GitHub repository. To create a new reposit
 
 ===== Use the plugin generator tool
 
-You can now create your own Logstash plugin in seconds! The `generate` subcommand of `bin/logstash-plugin` creates the foundation 
+You can create your own Logstash plugin in seconds! The `generate` subcommand of `bin/logstash-plugin` creates the foundation 
 for a new Logstash plugin with templatized files. It creates the correct directory structure, gemspec files, and dependencies so you 
 can start adding custom code to process data with Logstash.
 

docs/static/listing-a-plugin.asciidoc

@@ -0,0 +1,15 @@
+[[plugin-listing]]
+=== List your plugin
+
+The {logstash-ref}[Logstash Reference] is the first place {ls} users look for plugins and documentation. 
+If your plugin meets the <<plugin-acceptance,quality and acceptance guidelines>>, we may be able to list it in the guide.
+
+The plugin source and readme will continue to live in your repo, and we will direct users there. 
+
+If you would like to have your plugin included in the {logstash-ref}[Logstash Reference]: 
+
+* verify that it meets our <<plugin-acceptance,quality and acceptance guidelines>>
+* create a new https://github.com/elasticsearch/logstash/issues[issue] in the Logstash repository. 
+** Use `PluginListing: <yourpluginname>` as the title for the issue.
+** Apply the `docs` label.  
+** In the body of the issue, explain the purpose and value your plugin offers, and describe how this plugin adheres to the guidelines.

docs/static/plugin-generator.asciidoc

@@ -1,9 +1,9 @@
 [[plugin-generator]]
-=== Generating Plugins
+=== Generating plugins
 
-You can now create your own Logstash plugin in seconds! The generate subcommand of `bin/logstash-plugin` creates the foundation 
+You can create your own Logstash plugin in seconds! The generate subcommand of `bin/logstash-plugin` creates the foundation 
-for a new Logstash plugin with templatized files. It creates the correct directory structure, gemspec files, and dependencies so you 
+for a new Logstash plugin with templatized files. 
-can start adding custom code to process data with Logstash.
+It creates the correct directory structure, gemspec files, and dependencies so you can start adding custom code to process data with Logstash.
 
 **Example Usage**
 
@@ -14,6 +14,6 @@ bin/logstash-plugin generate --type input --name xkcd --path ~/ws/elastic/plugin
 
 * `--type`: Type of plugin - input, filter, output, or codec
 * `--name`: Name for the new plugin
-* `--path`: Directory path where the new plugin structure will be created. If not specified, it will be
+* `--path`: Directory path where the new plugin structure will be created. 
-created in the current directory.
+If you don't specify a directory, the plugin is created in the current directory.
 

docs/static/plugin-manager.asciidoc

@@ -6,8 +6,7 @@
 ====
 Apple's rollout of stricter notarization requirements affected the notarization
 of the {version} {ls} artifacts. If macOS Catalina displays a dialog when you
-first run {ls} that interrupts it, you will need to take an action to allow it
+first run {ls}, you need to take an action to allow it to run.
-to run.
 To prevent Gatekeeper checks on the {ls} files, run the following command on the
 downloaded `.tar.gz` archive or the directory to which was extracted:
 [source,sh]

docs/static/submitting-a-plugin.asciidoc

@@ -1,9 +1,9 @@
-[[submitting-plugin]]
+[[publish-plugin]]
-=== Submitting your plugin to RubyGems.org and the logstash-plugins repository
+=== Publish your plugin to RubyGems.org
 
-Logstash uses http://rubygems.org[RubyGems.org] as its repository for all plugin
+Logstash uses http://rubygems.org[RubyGems.org] as its repository for all plugin artifacts. 
-artifacts. Once you have developed your new plugin, you can make it available to
+After you have developed your new plugin, you can make it available to
-Logstash users by simply publishing it to RubyGems.org.
+Logstash users by publishing it to RubyGems.org.
 
 ==== Licensing
 Logstash and all its plugins are licensed under
@@ -13,9 +13,9 @@ please make sure to have this line in your gemspec:
 
 * `s.licenses = ['Apache License (2.0)']`
 
-==== Publishing to http://rubygems.org[RubyGems.org]
+==== Publish to http://rubygems.org[RubyGems.org]
 
-To begin, you’ll need an account on RubyGems.org
+You’ll need an account on RubyGems.org
 
 * https://rubygems.org/sign_up[Sign-up for a RubyGems account].
 
@@ -49,7 +49,7 @@ bundle exec rake publish_gem
 
 [NOTE]
 ========
-Executing `rake publish_gem`:
+Execute `rake publish_gem`:
 
 . Reads the version from the gemspec file (`s.version = '0.1.0'`)
 . Checks in your local repository if a tag exists for that version. If the tag
@@ -68,40 +68,6 @@ by running:
 bin/plugin install logstash-{plugintype}-mypluginname
 ----------------------------------
 
-==== Contributing your source code to https://github.com/logstash-plugins[logstash-plugins]
+Where <plugintype> is `input`, `output`, `filter`, or `codec`, and
-
+<mypluginname> is the name of your new plugin.
-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
-
-Some of the many benefits of having your plugin in the logstash-plugins
-repository are:
-
-* **Discovery** Your plugin will appear in the {logstash-ref}[Logstash Reference],
-where Logstash users look first for plugins and documentation.
-* **Documentation** Your plugin documentation will automatically be added to the 
-{logstash-ref}[Logstash Reference].
-* **Testing** With our testing infrastructure, your plugin will be continuously
-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
-
-* **Code Review** Your plugin must be reviewed by members of the community for
-coherence, quality, readability, stability and security.
-* **Tests** Your plugin must contain tests to be accepted.  These tests are also
-subject to code review for scope and completeness.  It's ok if you don't know
-how to write tests -- we will guide you. We are working on publishing a guide to
-creating tests for Logstash which will make it easier.  In the meantime, you can
-refer to http://betterspecs.org/ for examples.
-
-To begin migrating your plugin to logstash-plugins, simply create a new
-https://github.com/elasticsearch/logstash/issues[issue] in
-the Logstash repository. When the acceptance guidelines are completed, we will
-facilitate the move to the logstash-plugins organization using the recommended
-https://help.github.com/articles/transferring-a-repository/#transferring-from-a-user-to-an-organization[github process].
-