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

Adds Maintainer's Guide section.

Browse source
This commit is contained in:
Paul Echeverri 2015-11-11 15:19:14 -08:00 • committed by Suyog Rao
parent 8de54e46ce
commit 906dab7c39
2 changed files with 157 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -46,3 +46,5 @@ 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.
include::maintainer-guide.asciidoc[]

155
docs/asciidoc/static/maintainer-guide.asciidoc Normal file
View file

@ -0,0 +1,155 @@
[[community-maintainer]]
== Logstash Plugins Community Maintainer Guide
This document, to be read by new Maintainers, should explain their responsibilities. It was inspired by the
http://rfc.zeromq.org/spec:22[C4] document from the ZeroMQ project. This document is subject to change and suggestions
through Pull Requests and issues are strongly encouraged.
=== Contribution Guidelines
For general guidance around contributing to Logstash Plugins, see the
https://www.elastic.co/guide/en/logstash/current/contributing-to-logstash.html[_Contributing to Logstash_] section.
=== Document Goals
To help make the Logstash plugins community participation easy with positive feedback.
To increase diversity.
To reduce code review, merge and release dependencies on the core team by providing support and tools to the Community and
Maintainers.
To support the natural life cycle of a plugin.
To codify the roles and responsibilities of: Maintainers and Contributors with specific focus on patch testing, code
review, merging and release.
=== Development Workflow
All Issues and Pull Requests must be tracked using the Github issue tracker.
The plugin uses the http://www.apache.org/licenses/LICENSE-2.0[Apache 2.0 license]. Maintainers should check whether a
patch introduces code which has an incompatible license. Patch ownership and copyright is defined in the Elastic
https://www.elastic.co/contributor-agreement[Contributor License Agreement] (CLA).
==== Terminology
A "Contributor" is a role a person assumes when providing a patch. Contributors will not have commit access to the
repository. They need to sign the Elastic https://www.elastic.co/contributor-agreement[Contributor License Agreement]
before a patch can be reviewed. Contributors can add themselves to the plugin Contributor list.
A "Maintainer" is a role a person assumes when maintaining a plugin and keeping it healthy, including triaging issues, and
reviewing and merging patches.
==== Patch Requirements
A patch is a minimal and accurate answer to exactly one identified and agreed upon problem. It must conform to the code
style guidelines and must include RSpec tests that verify the fitness of the solution.
A patch will be automatically tested by a CI system that will report on the Pull Request status.
A patch CLA will be automatically verified and reported on the Pull Request status.
A patch commit message has a single short (less than 50 character) first line summarizing the change, a blank second line,
and any additional lines as necessary for change explanation and rationale.
A patch is mergeable when it satisfies the above requirements and has been reviewed positively by at least one other
person.
==== Development Process
A user will log an issue on the issue tracker describing the problem they face or observe with as much detail as possible.
To work on an issue, a Contributor forks the plugin repository and then works on their forked repository and submits a
patch by creating a pull request back to the plugin.
Maintainers must not merge patches where the author has not signed the CLA.
Before a patch can be accepted it should be reviewed. Maintainers should merge accepted patches without delay.
Maintainers should not merge their own patches except in exceptional cases, such as non-responsiveness from other
Maintainers or core team for an extended period (more than 2 weeks).
Reviewer’s comments should not be based on personal preferences.
The Maintainers should label Issues and Pull Requests.
Maintainers should involve the core team if help is needed to reach consensus.
Review non-source changes such as documentation in the same way as source code changes.
==== Branch Management
The plugin has a master branch that always holds the latest in-progress version and should always build. Topic branches
should kept to the minimum.
=== Versioning Plugins
Logstash core and its plugins have separate product development lifecycles. Hence the versioning and release strategy for
the core and plugins do not have to be aligned. In fact, this was one of our goals during the great separation of plugins
work in Logstash 1.5.
At times, there will be changes in core API in Logstash, which will require mass update of plugins to reflect the changes
in core. However, this does not happen frequently.
For plugins, we would like to adhere to a versioning and release strategy that can better inform our users, about any
breaking changes to the Logstash configuration formats and functionality.
Plugin releases follows a three-placed numbering scheme X.Y.Z. where X denotes a major release version which may break
compatibility with existing configuration or functionality. Y denotes releases which includes features which are backward
compatible. Z denotes releases which includes bug fixes and patches.
==== Changing the version
Version can be changed in the Gemspec, which needs to be associated with a changelog entry. Following this, we can publish
the gem to RubyGem.org manually. At this point only the core developers can publish a gem.
==== Labeling
Labeling is a critical aspect of maintaining plugins. All issues in GitHub should be labeled correctly so it can:
* Provide good feedback to users/developers
* Help prioritize changes
* Be used in release notes
Most labels are self explanatory, but here’s a quick recap of few important labels:
* `bug`: Labels an issue as an unintentional defect
* `needs details`: If a the issue reporter has incomplete details, please ask them for more info and label as needs
details.
* `missing cla`: Contributor License Agreement is missing and patch cannot be accepted without it
* `adopt me`: Ask for help from the community to take over this issue
* `enhancement`: New feature, not a bug fix
* `needs tests`: Patch has no tests, and cannot be accepted without unit/integration tests
* `docs`: Documentation related issue/PR
=== Logging
Although it’s important not to bog down performance with excessive logging, debug level logs can be immensely helpful when
diagnosing and troubleshooting issues with Logstash. Please remember to liberally add debug logs wherever it makes sense
as users will be forever gracious.
[source,shell]
@logger.debug("Logstash loves debug logs!", :actions => actions)
=== Contributor License Agreement (CLA) Guidance
[qanda]
Why is a https://www.elastic.co/contributor-agreement[CLA] required?::
We ask this of all Contributors in order to assure our users of the origin and continuing existence of the code. We
are not asking Contributors to assign copyright to us, but to give us the right to distribute a Contributor’s code
without restriction.
Please make sure the CLA is signed by every Contributor prior to reviewing PRs and commits.::
Contributors only need to sign the CLA once and should sign with the same email as used in Github. If a Contributor
signs the CLA after a PR is submitted, they can refresh the automated CLA checker by pushing another
comment on the PR after 5 minutes of signing.
=== Community Administration
The core team is there to support the plugin Maintainers and overall ecosystem.
Maintainers should propose Contributors to become a Maintainer.
Contributors and Maintainers should follow the Elastic Community https://www.elastic.co/community/codeofconduct[Code of
Conduct]. The core team should block or ban "bad actors".