Skip to content

Latest commit

 

History

History
248 lines (190 loc) · 8.17 KB

contributing.md

File metadata and controls

248 lines (190 loc) · 8.17 KB
Raw

Contributing to Datadog Agent

First of all, thanks for contributing!

This document provides some basic guidelines for contributing to this repository. To propose improvements, feel free to submit a PR.

Submitting issues

Pull Requests

Have you fixed a bug or written a new check and want to share it? Many thanks!

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

  • have a proper commit history (we advise you to rebase if needed).
  • write tests for the code you wrote.
  • preferably make sure that all tests pass locally.
  • summarize your PR with an explanatory title and a message describing your changes, cross-referencing any related bugs/PRs.
  • use Reno to create a releasenote.
  • open your PR against the master branch.
  • for PRs from contributors with write access to the repository (for community PRs, will be done by Datadog employees):
    • set the relevant team/ label
    • add a milestone to your PR (by default, use the highest milestone version available, ex: 6.8.0)

Your pull request must pass all CI tests before we will merge it. If you're seeing an error and don't think it's your fault, it may not be! Join us on Slack or send us an email, and together we'll get it sorted out.

Keep it small, focused

Avoid changing too many things at once. For instance if you're fixing the NTP check and at the same time shipping a dogstatsd improvement, it makes reviewing harder and the time-to-release longer.

Commit Messages

Please don't be this person: git commit -m "Fixed stuff". Take a moment to write meaningful commit messages.

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.

This includes editing the commit message generated by Github from:

Including new features

* Fix linter
* WIP
* Add test for x86
* Fix licenses
* Cleanup headers

to:

Including new features

This feature does this and that. Some tests are excluded on x86 because of ...

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 give that slot to someone else who does need it.

Squash your commits

Please rebase your changes on master and squash your commits whenever possible, it keeps history cleaner and it's easier to revert things. It also makes developers happier!

Reno

We use Reno to create our CHANGELOG. Reno is a pretty simple tool.

Each PR should include a releasenotes file created with reno, unless the PR doesn't have any impact on the behavior of the Agent and therefore shouldn't be mentioned in the CHANGELOG (examples: repository documentation updates, changes in code comments). PRs that don't require a release note file will be labeled changelog/no-changelog by maintainers.

To install reno: pip install reno

Ultra quick Reno HOWTO:

$> reno new <topic-of-my-pr> --edit
[...]
# Remove unused sections and fill the relevant ones.
# Reno will create a new file in releasenotes/notes.
#
# Each section from every release note are combined when the CHANGELOG.rst is
# rendered. So the text needs to be worded so that it does not depend on any
# information only available in another section. This may mean repeating some
# details, but each section must be readable independently of the other.
#
# Each section note must be formatted as reStructuredText.
[...]

Then just add and commit the new releasenote (located in releasenotes/notes/) with your PR. If the change is on the trace-agent (folders cmd/trace-agent or pkg/trace) please prefix the release note with "APM :" and the argument with "apm-".

Reno sections

The main thing to keep in mind is that the CHANGELOG is written for the agent's users and not its developers.

  • features: describe shortly what your feature does.

    example:

    features:
  - |
    Introducing the Datadog Process Agent for Windows.

  • enhancements: describe enhancements here: new behavior that are too small to be considered a new feature.

    example:

    enhancements:
  - |
    Windows: Add PDH data to flare.

  • issues: describe known issues or limitation of the agent.

    example:

    issues:
  - |
    Kubernetes 1.3 & OpenShift 3.3 are currently not fully supported: docker
    and kubelet integrations work OK, but apiserver communication (event
    collection, `kube_service` tagging) is not implemented

  • upgrade: List actions to take or limitations that could arise upon upgrading the Agent. Notes here must include steps that users can follow to 1. know if they're affected and 2. handle the change gracefully on their end.

    example:

    upgrade:
  - |
    If you run a Nomad agent older than 0.6.0, the `nomad_group`
    tag will be absent until you upgrade your orchestrator.

  • deprecations: List deprecation notes here.

    example:

    deprecations:
- |
  Changed the attribute name to enable log collection from YAML configuration
  file from "log_enabled" to "logs_enabled", "log_enabled" is still
  supported.

  • security: List security fixes, issues, warning or related topics here.

    example:

    security:
  - |
    The /agent/check-config endpoint has been patched to enforce
    authentication of the caller via a bearer session token.

  • fixes: List the fixes done in your PR here. Remember to be clear and give a minimum of context so people reading the CHANGELOG understand what the fix is about.

    example:

    fixes:
  - |
    Fix EC2 tags collection when multiple marketplaces are set.

  • other: Add here every other information you want in the CHANGELOG that don't feat in any other section. This section should rarely be used.

    example:

    other:
  - |
    Only enable the ``resources`` metadata collector on Linux by default, to match
    Agent 5's behavior.

PR labels

For internal PRs (from people in the Datadog organisation), you have few extra labels that can be use:

  • community/help-wanted: for community PRs where help is needed to finish it.
  • community: for community PRs.
  • changelog/no-changelog: for PRs that don't require a reno releasenote (useful for PRs only changing documentation or tests).
  • qa/skip-qa: this will skip creating a QA card for the PR during the release process (example: for a documentation only PRs).
  • major_change: to flag the PR as a major change impacting many/all teams working on the agent and will require deeper QA (example: when we change the Python version shipped in the agent).

Integrations

Also called checks, all officially supported Agent integrations live in the integrations-core repo. Please look there to submit related issues, PRs, or review the latest changes. For new integrations, please open a pull request in the integrations-extras repo.