[[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. After committing your code, check out the
https://www.elastic.co/community/contributor[Elastic Contributor Program]
where you can earn points and rewards for your contributions.

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>>. New PRs go to the master branch. The Beats
core team will backport your PR if it is necessary.


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.

[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, make and mage to generate configuration files
and documentation. The primary command used for this is:

[source,shell]
--------------------------------------------------------------------------------
make update
--------------------------------------------------------------------------------
Each Beat has its own `update` target, as well as a master `update` in the repository root. 
If a PR adds or removes a dependency, run `make update` in the root `beats` directory.

Another command properly formats go source files and adds a copyright header:

[source,shell]
--------------------------------------------------------------------------------
make fmt
--------------------------------------------------------------------------------

Both of these commands should be run before submitting a PR. You can view all
the available make targets with `make help`.

These commands have the following dependencies:

* Python >= {python}
* Python https://docs.python.org/3/library/venv.html[venv module]
* https://github.com/magefile/mage[Mage]

Python venv module is included in the standard library in Python 3. On Debian/Ubuntu
systems it also requires to install the `python3-venv` package, that includes
additional support scripts:

[source,shell]
--------------------------------------------------------------------------------
sudo apt-get install python3-venv
--------------------------------------------------------------------------------

[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

In order to create Beats we rely on Golang libraries and other
external tools.

[float]
==== Golang

To manage the `vendor/` folder we use go modules.

To update the contents of `vendor/`, run `mage vendor`.

[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].
