Skip to content

Latest commit

 

History

History
164 lines (120 loc) · 6.92 KB

CONTRIBUTING.md

File metadata and controls

164 lines (120 loc) · 6.92 KB
Raw

Contributing to opentelemetry-cpp

The OpenTelemetry C/C++ special interest group (SIG) meets regularly. See the OpenTelemetry community repo for information on this and other language SIGs.

See the public meeting notes for a summary description of past meetings. To request edit access, join the meeting or get in touch on Gitter.

See the community membership document on how to become a Member, Approver and Maintainer.

Development

OpenTelemetry C++ uses the Google naming convention.

Code is formatted automatically and enforced by CI.

Build and Run Code Examples

Note: these instructions apply to examples configured with Bazel, see example-specific documentation for other build automation tools.

Install the latest bazel version by following the steps listed here.

Select an example of interest from the examples folder. Inside each example directory is a BUILD file containing instructions for Bazel. Find the binary name of your example by inspecting the contents of this BUILD file.

Build the example from the root of the opentelemetry-cpp directory using Bazel. Replace <binary name> with the identifier found in the previous step:

bazel build //examples/<example directory name>:<binary name>

Run the resulting executable to see telemetry from the application as it calls the instrumented library: 

bazel-bin/examples/<example directory name>/<binary name>

For instance, building and running the simple example can be done as follows:

bazel build //examples/simple:example_simple
bazel-bin/examples/simple/example_simple

Pull Requests

How to Send Pull Requests

Everyone is welcome to contribute code to opentelemetry-cpp via GitHub pull requests (PRs).

To create a new PR, fork the project in GitHub and clone the upstream repo:

git clone https://github.com/open-telemetry/opentelemetry-cpp.git

Add your fork as a remote:

git remote add fork https://github.com/YOUR_GITHUB_USERNAME/opentelemetry-cpp.git

Check out a new branch, make modifications and push the branch to your fork:

git checkout -b feature
# edit files
tools/format.sh
git commit
git push fork feature

Open a pull request against the main opentelemetry-cpp repo.

To run tests locally, please read the CI instructions.

How to Receive Comments

  • If the PR is not ready for review, please put [WIP] in the title, tag it as work-in-progress, or mark it as draft.
  • Make sure CLA is signed and CI is clear.

How to Get PRs Merged

A PR is considered to be ready to merge when:

  • It has received two approvals from Approvers / Maintainers (at different companies).
  • Major feedback items/points are resolved.
  • It has been open for review for at least one working day. This gives people reasonable time to review.
  • Trivial changes (typo, cosmetic, doc, etc.) don't have to wait for one day.
  • Urgent fixes can take exceptions as long as it has been actively communicated.

Any Approver / Maintainer can merge the PR once it is ready to merge.

Useful Resources

Hi! If you’re looking at this document, these resources will provide you the knowledge to get started as a newcomer to the OpenTelemetry project. They will help you understand the OpenTelemetry Project, its components, and specifically the C++ repository.

Reading Resources

  • Medium article (October 2019) on how to start contributing to the OpenTelemetry project.
  • Medium article (January 2020) describing the overarching goals and use cases for OpenTelemetry.

Relevant Documentation

  • OpenTelemetry Specification

    • The OpenTelemetry Specification describes the requirements and expectations of for all OpenTelemetry implementations.

  • Read through the OpenTelemetry Collector GitHub repository.

    • This repository has a lot of good information surrounding the OpenTelemetry ecosystem. At the top of the readme, there are multiple links that give newcomers a good idea of what the project is about and how to get involved in it.

  • Read through the OpenTelemetry Python documentation

    • The API and SDK documentation provides a lot of information on what the classes and their functions are used for. Since there is currently minimal documentation for C++, use the Python repository’s extensive documentation to learn more about how the API and SDK work.

Code Examples

  • Follow the simple trace example for an introduction to basic OpenTelemetry functionality in C++. Currently the example can be found in PR #94.

  • Read through the Java Quick-Start Guide. This shows you how the classes and functions will interact in simple and easy to digest examples.

  • Take a look at this Java SDK example. This shows a good use case of the SDK using stdout exporter.

  • Take a look at the Java Jaeger example. This provides a brief introduction to the Jaeger exporter, its interface, and how to interact with the service.

Please contribute! You’re welcome to add more information if you come across any helpful resources.