Skip to content

Latest commit

 

History

History
221 lines (145 loc) · 8.68 KB

CONTRIBUTING.md

File metadata and controls

221 lines (145 loc) · 8.68 KB
Raw

Contributing to Datadog Agent

🎉 First of all, thanks for contributing! 🎉

This document aims to provide some basic guidelines to contribute to this repository, but keep in mind that these are just guidelines, not rules; use your best judgment and feel free to propose changes to this document in a pull request.

Submitting issues

Pull Requests

You wrote some code/added a new check and want to share it? Thanks a lot for your interest!

In order to ease/speed up our review, here are some items you can check/improve when submitting your PR:

Your Pull Request must always pass the Travis/Appveyor tests before being merged, if you think the error is not due to your changes, you can have a talk with us on IRC (#datadog freenode) or send us an email to support at datadoghq dot com)

If you are adding a dependency (python module, library, ...), please check the corresponding section.

Commits

Keep it small, focused

Avoid changing too many things at once, for instance if you're fixing the redis integration and at the same time shipping a dogstatsd improvement, it makes reviewing harder (devs specialize in different parts of the code) and the change time-to-release longer.

Bisectability

Every commit should lead to a valid code, at least a code in a better state than before. That means that every revision should be able to pass unit and integration tests (more about testing)

An example of something which breaks bisectability:

  • commit 1: Added check X
  • commit 2: forgot column
  • commit 3: fix typo

To avoid that, please rebase your changes and create valid commits. It keeps history cleaner, it's easier to revert things, and it makes developers happier too.

Messages

Please don't use git commit -m "Fixed stuff", it usually means that you just wrote the very first thing that came to your mind without much thought. Also it makes navigating through the code history harder.

Instead, the commit shortlog should focus on describing the change in a sane way (see commits titles) and be short (72 columns is best).

The commit message should describe the reason for the change and give extra details that will allow someone later on to understand in 5 seconds the thing you've been working on for a day.

If your commit is only shipping documentation changes or example files, and is a complete no-op for the test suite, please add [skip ci] in the commit message body to skip the build and let you build slot to someone else in need 😉

Examples, see:

Commits titles

Every commit title, PR or issue should be named like the following example:

[category] short description of the matter

category can be:

  • core: for the agent internals, or the common interfaces
  • dogstatsd: for the embedded dogstatsd server
  • tests: related to CI, integration & unit testing
  • dev: related to development or tooling
  • check_name: specific to one check

For descriptions, keep it short keep it meaningful. Here are a few examples to illustrate.

Bad descriptions

  • [mysql] mysql check does not work
  • [snmp] improved snmp
  • [core] refactored stuff

Good descriptions

  • [mysql] exception ValueError on mysql 5.4
  • [snmp] added timeouts to snmpGet calls
  • [core] add config option to common metric interface

Tests

Please refer to this document.

Add dependencies

You wrote a new agent check which uses a python module not embedded in the agent yet? You're at the right place to correct this!

We use Omnibus to build our agent and bundle all dependencies. We define what are the agent dependencies in the dd-agent-omnibus repository, and we define how to build/add these dependencies in the omnibus-software repository.

To add a new module, you will have to update both.

Python module without external dependencies

If you want to add a module which is pure python, installed with pip, without any compilation/external dependencies, it's really easy.

omnibus-software

First, fork omnibus-software, create your branch, and add a my_module.rb file in config/software/.

Then copy/paste these instructions:

name "my_module"
default_version "9.9.9"

dependency "python"
dependency "pip"

build do
  license "https://url.to.my/LICENSE.txt"
  command "#{install_dir}/embedded/bin/pip install -I --install-option=\"--install-scripts=#{install_dir}/bin\" #{name}==#{version}"
end

And replace, my_module with your module name, default_version by the version you want, then provide a URL to the module license (replacing "https://url.to.my/LICENSE.txt").

And it's done for omnibus-software!

dd-agent-omnibus

First, fork omnibus-software, and create your branch.

Then add dependency "my_module" to config/projects/datadog-agent.rb: (please respect alphabetical sort)

# Check dependencies
dependency "kafka-python"
dependency "kazoo"
dependency "my_module"
dependency "paramiko"
dependency "pg8000"

And it's over! Don't forget to submit your two PRs (and to cross-reference them).

Python module with external dependency

Your python module also needs an external lib? That's not a problem with Omnibus, it just needs a little more work.

omnibus-software

First, fork omnibus-software and create your branch.

Let's keep it simple, and suppose that you want to add a python module my_module which depends on a library my_lib.

Create a my_lib.rb file in config/software/.

Then add instructions to compile it from source and install it at the right place (this is for instance libsqlite3.rb):

name "my_lib"
default_version "9.9.9"

source :git => 'git://github.com/my_lib/my_lib.git'

relative_path 'my_lib'

env = {
  "LDFLAGS" => "-L#{install_dir}/embedded/lib -I#{install_dir}/embedded/include",
  "CFLAGS" => "-L#{install_dir}/embedded/lib -I#{install_dir}/embedded/include",
  "LD_RUN_PATH" => "#{install_dir}/embedded/lib"
}

build do
  command(["./configure",
       "--prefix=#{install_dir}/embedded",
       "--disable-nls"].join(" "),
    :env => env)
  command "make -j #{workers}", :env => {"LD_RUN_PATH" => "#{install_dir}/embedded/lib"}
  command "sudo make install"
end

You will probably have to adapt the build instructions, depending on your lib.

Then create the my_module.rb file and copy/paste these instructions:

name "my_module"
default_version "9.9.9"

dependency "my_lib"
dependency "python"
dependency "pip"

build do
  license "https://url.to.my/LICENSE.txt"
  command "#{install_dir}/embedded/bin/pip install -I --install-option=\"--install-scripts=#{install_dir}/bin\" #{name}==#{version}"
end

And replace, my_module with your module name, default_version with the version you want, my_lib with the name of the required lib, then provide a URL to the module license (replacing "https://url.to.my/LICENSE.txt").

If you need to install it with python setup.py install, take a look at this example. (which also demonstrate the use of a patch).

And it's done for omnibus-software!

dd-agent-omnibus

First, fork omnibus-software, and create your branch.

Then add dependency "my_module" to config/projects/datadog-agent.rb: (please respect alphabetical sort)

# Check dependencies
dependency "kafka-python"
dependency "kazoo"
dependency "my_module"
dependency "paramiko"
dependency "pg8000"

And it's over! Don't forget to submit your two PRs (and to cross-reference them).