diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a3b18e248a..daacc9e7f0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,6 +20,33 @@ convention](https://google.github.io/styleguide/cppguide.html#Naming). 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 `` with the identifier found in the previous step: + +```sh +bazel build //examples/: +``` + +Run the resulting executable to see telemetry from the application as it calls the instrumented library: + +```sh +bazel-bin/examples// +``` + +For instance, building and running the `simple` example can be done as follows: + +```sh +bazel build //examples/simple:example_simple +bazel-bin/examples/simple/example_simple +``` + ## Pull Requests ### How to Send Pull Requests @@ -72,3 +99,33 @@ A PR is considered to be **ready to merge** when: * 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 Open Telemetry project. They will help you understand the Open Telemetry Project, its components, and specifically the C++ repository. + +### Reading Resources + +* Medium [article](https://medium.com/opentelemetry/how-to-start-contributing-to-opentelemetry-b23991ad91f4) (October 2019) on how to start contributing to the Open Telemetry project. +* Medium [article](https://medium.com/opentelemetry/opentelemetry-beyond-getting-started-5ac43cd0fe26) (January 2020) describing the overarching goals and use cases for Open Telemetry. + +### Relevant Documentation + +* Open Telemetry [Specification](https://github.com/open-telemetry/opentelemetry-specification) + * The Open Telemetry Specification describes the requirements and expectations of for all Open Telemetry implementations. + +* Read through the [Open Telemetry Collector](https://github.com/open-telemetry/opentelemetry-collector) GitHub repository + * This repository has a lot of good information surrounding the Open Telemetry ecosystem. At the top of the **[readme](https://github.com/open-telemetry/opentelemetry-collector/blob/master/README.md)**, 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 Open Telemetry Python documentation + * The [API](https://opentelemetry-python.readthedocs.io/en/stable/api/api.html) and [SDK](https://opentelemetry-python.readthedocs.io/en/stable/sdk/sdk.html) 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](https://github.com/open-telemetry/opentelemetry-cpp/pull/92) for an introduction to basic Open Telemetry functionality in C++. Currently the example can be found in [PR #94](https://github.com/open-telemetry/opentelemetry-cpp/pull/94) + +* Read through the [Java Quick-Start Guide](https://github.com/open-telemetry/opentelemetry-java/blob/master/QUICKSTART.md) + * 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.](https://github.com/open-telemetry/opentelemetry-java/tree/master/examples/sdk-usage) This shows a good use case of the SDK using stdout exporter. +* Take a look at the [Java Jaeger example.](https://github.com/open-telemetry/opentelemetry-java/tree/master/examples/jaeger) 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. \ No newline at end of file