Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Useful Resources and Example Build Instructions to CONTRIBUTING.md #97

Merged
merged 4 commits into from
Jun 9, 2020
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 57 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <a href="https://docs.bazel.build/versions/master/install.html">here</a>

Select an example of interest from the <a href="https://github.com/open-telemetry/opentelemetry-cpp/tree/master/examples"> examples folder </a>. 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:

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

Run the resulting executable to see telemetry from the application as it calls the instrumented library: </li>

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

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
Expand Down Expand Up @@ -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)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When this is merged, can you submit an issue that reminds us of updating this document before we do a first release? Once we have our own examples and exporters in place, many of the examples here should be switched out.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I'll get that issue up once this PR this merged


* 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.