mirror of
https://github.com/Icinga/icingabeat.git
synced 2025-11-12 17:09:59 +01:00
181 lines
7.0 KiB
Plaintext
181 lines
7.0 KiB
Plaintext
[[beats-contributing]]
|
|
== Contributing to Beats
|
|
|
|
If you have a bugfix or new feature that you would like to contribute, please
|
|
start by opening a topic on the https://discuss.elastic.co/c/beats[forums].
|
|
It may be that somebody is already working on it, or that there are particular
|
|
issues that you should know about before implementing the change.
|
|
|
|
We enjoy working with contributors to get their code accepted. There are many
|
|
approaches to fixing a problem and it is important to find the best approach
|
|
before writing too much code.
|
|
|
|
The process for contributing to any of the Elastic repositories is similar.
|
|
|
|
[float]
|
|
[[contribution-steps]]
|
|
=== Contribution Steps
|
|
|
|
. Please make sure you have signed our
|
|
https://www.elastic.co/contributor-agreement/[Contributor License Agreement]. We
|
|
are not asking you to assign copyright to us, but to give us the right to
|
|
distribute your code without restriction. We ask this of all contributors in
|
|
order to assure our users of the origin and continuing existence of the code.
|
|
You only need to sign the CLA once.
|
|
|
|
. Send a pull request! Push your changes to your fork of the repository and
|
|
https://help.github.com/articles/using-pull-requests[submit a pull request] using our
|
|
<<pr-review,pull request guidelines>>. In the pull request, describe what your changes do and mention
|
|
any bugs/issues related to the pull request. Please also add a changelog entry to
|
|
https://github.com/elastic/beats/blob/master/CHANGELOG.next.asciidoc[CHANGELOG.next.asciidoc].
|
|
|
|
[float]
|
|
[[adding-new-beat]]
|
|
=== Adding a New Beat
|
|
|
|
If you want to create a new Beat, please read <<new-beat>>. You don't need to
|
|
submit the code to this repository. Most new Beats start in their own repository
|
|
and just make use of the libbeat packages. After you have a working Beat that
|
|
you'd like to share with others, open a PR to add it to our list of
|
|
https://github.com/elastic/beats/blob/master/libbeat/docs/communitybeats.asciidoc[community
|
|
Beats].
|
|
|
|
[float]
|
|
[[setting-up-dev-environment]]
|
|
=== Setting Up Your Dev Environment
|
|
|
|
The Beats are Go programs, so install the {go-version} version of
|
|
http://golang.org/[Go] which is being used for Beats development.
|
|
|
|
After https://golang.org/doc/install[installing Go], set the
|
|
https://golang.org/doc/code.html#GOPATH[GOPATH] environment variable to point to
|
|
your workspace location, and make sure `$GOPATH/bin` is in your PATH.
|
|
|
|
The location where you clone is important. Make a directory structure under
|
|
`GOPATH` that matches the URL used for Elastic repositories, then clone the
|
|
beats repository under the new directory:
|
|
|
|
[source,shell]
|
|
----------------------------------------------------------------------
|
|
mkdir -p ${GOPATH}/src/github.com/elastic
|
|
git clone https://github.com/elastic/beats ${GOPATH}/src/github.com/elastic/beats
|
|
----------------------------------------------------------------------
|
|
|
|
NOTE: If you have multiple go paths, use `${GOPATH%%:*}` instead of `${GOPATH}`.
|
|
|
|
Then you can compile a particular Beat by using the Makefile. For example, for
|
|
Packetbeat:
|
|
|
|
[source,shell]
|
|
--------------------------------------------------------------------------------
|
|
cd beats/packetbeat
|
|
make
|
|
--------------------------------------------------------------------------------
|
|
|
|
Some of the Beats might have extra development requirements, in which case
|
|
you'll find a CONTRIBUTING.md file in the Beat directory.
|
|
|
|
We use an http://editorconfig.org/[EditorConfig] file in the beats repository
|
|
to standardise how different editors handle whitespace, line endings, and other
|
|
coding styles in our files. Most popular editors have a
|
|
http://editorconfig.org/#download[plugin] for EditorConfig and we strongly
|
|
recommend that you install it.
|
|
|
|
[float]
|
|
[[update-scripts]]
|
|
=== Update scripts
|
|
|
|
The Beats use a variety of scripts based on Python to generate configuration files
|
|
and documentation. The primary command used for this is:
|
|
|
|
[source,shell]
|
|
--------------------------------------------------------------------------------
|
|
make update
|
|
--------------------------------------------------------------------------------
|
|
|
|
Another command properly formats go source files and adds a copyright header:
|
|
|
|
[source,shell]
|
|
--------------------------------------------------------------------------------
|
|
make fmt
|
|
--------------------------------------------------------------------------------
|
|
|
|
These commands have the following dependencies:
|
|
|
|
* Python >= {python}
|
|
* https://virtualenv.pypa.io/en/latest/[virtualenv] for Python
|
|
|
|
Virtualenv can be installed with the command `easy_install virtualenv` or `pip
|
|
install virtualenv`. More details can be found
|
|
https://virtualenv.pypa.io/en/latest/installation.html[here]. Both of these commands should be run before submitting a PR. You can view all the available make targets with `make help`.
|
|
|
|
|
|
[float]
|
|
[[build-target-env-vars]]
|
|
=== Selecting Build Targets
|
|
|
|
Beats is built using the `make release` target. By default, make will select from a limited number of preset build targets:
|
|
|
|
- darwin/amd64
|
|
- linux/386
|
|
- linux/amd64
|
|
- windows/386
|
|
- windows/amd64
|
|
|
|
You can change build targets using the `PLATFORMS` environment variable. Targets set with the `PLATFORMS` variable can either be a GOOS value, or a GOOS/arch pair.
|
|
For example, `linux` and `linux/amd64` are both valid targets. You can select multiple targets, and the `PLATFORMS` list is space delimited, for example `darwin windows` will build on all supported darwin and windows architectures.
|
|
In addition, you can add or remove from the list of build targets by prepending `+` or `-` to a given target. For example: `+bsd` or `-darwin`.
|
|
|
|
You can find the complete list of supported build targets with `go tool dist list`.
|
|
|
|
|
|
|
|
[float]
|
|
[[running-testsuite]]
|
|
=== Testing
|
|
|
|
You can run the whole testsuite with the following command:
|
|
|
|
[source,shell]
|
|
--------------------------------------------------------------------------------
|
|
make testsuite
|
|
--------------------------------------------------------------------------------
|
|
|
|
Running the testsuite has the following requirements:
|
|
|
|
* Python >= {python}
|
|
* Docker >= {docker}
|
|
* Docker-compose >= {docker-compose}
|
|
|
|
For more details check the <<testing>> guide.
|
|
|
|
|
|
[float]
|
|
[[documentation]]
|
|
=== Documentation
|
|
|
|
The documentation for each Beat is located under `{beatname}/docs` and is based
|
|
on asciidoc. After changing the docs, you should verify that the docs are still
|
|
building to avoid breaking the automated docs build. To build the docs run
|
|
`make docs`. If you want to preview the docs for a specific Beat, run
|
|
`make docs-preview` inside the folder for the Beat. This will automatically open
|
|
your browser with the docs for preview.
|
|
|
|
[float]
|
|
[[dependencies]]
|
|
=== Dependencies
|
|
|
|
To manage the `vendor/` folder we use
|
|
https://github.com/kardianos/govendor[govendor]. Please see
|
|
the govendor documentation on how to add or update vendored dependencies.
|
|
|
|
In most cases `govendor fetch your/dependency@version +out` will get the job done.
|
|
|
|
[float]
|
|
[[changelog]]
|
|
=== Changelog
|
|
|
|
To keep up to date with changes to the official Beats for community developers,
|
|
follow the developer changelog
|
|
https://github.com/elastic/beats/blob/master/CHANGELOG-developer.next.asciidoc[here].
|