Contributing to opentelemetry-dotnet: A Comprehensive Guide for Developers

The OpenTelemetry .NET project welcomes contributions from the developer community. In this guide, we’ll walk you through the process of getting started, setting up your development environment, and making pull requests.

Find a Buddy and Get Started Quickly

If you’re new to contributing to OpenTelemetry .NET and would like some guidance, join the OpenTelemetry .NET Slack channel and find a buddy!

1. Create your CNCF Slack account and join the otel-dotnet channel.
2. Post an introduction in the room, mentioning your area of interest and your desire for a buddy.

Your OpenTelemetry buddy will be your resource for all aspects of contributing to OpenTelemetry, including providing context, reviewing pull requests, and helping you get your contributions merged.

Development Environment

To contribute to OpenTelemetry .NET, you’ll need the following prerequisites:

• Git client and command line tools.
• .NET 8.0 or higher.

Linux or macOS

• Visual Studio 2022 for Mac or Visual Studio Code.

Windows

• Visual Studio 2022 or Visual Studio Code.
• .NET Framework 4.6.2 or higher.

Public API

To maintain a small and clean public API surface, OpenTelemetry .NET uses Microsoft.CodeAnalysis.PublicApiAnalyzers to validate public APIs. This analyzer checks for changes to public properties/methods and ensures that OpenTelemetry doesn’t expose APIs outside of its primary concerns.

Enabling and Configuring

1. Create a .publicApi folder in your project with subfolders for each targeted framework.
2. Create two files called PublicAPI.Shipped.txt and PublicAPI.Unshipped.txt in each framework folder.
3. Add the following lines to your csproj file:

<ItemGroup>
<AdditionalFiles Include=".publicApi\$(TargetFramework)\PublicAPI.Shipped.txt" />
<AdditionalFiles Include=".publicApi\$(TargetFramework)\PublicAPI.Unshipped.txt" />
</ItemGroup>

4. Use IntelliSense to update the publicApi files.

Pull Requests

Sending Pull Requests

To create a new pull request, follow these steps:

1. Fork the project on GitHub.
2. Clone the upstream repository:

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

3. Add your fork as an origin:

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

4. Run tests:

dotnet test

5. If you made changes to Markdown documents, install the latest markdownlint-cli and run:

markdownlint .

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

$ git checkout -b feature
# edit files
$ git commit
$ git push fork feature

7. Open a pull request against the main opentelemetry-dotnet repo.

Receiving Comments

To increase the chances of your pull request being merged, follow these guidelines:

• Mark it as a draft if it’s not ready for review.
• Ensure your Contributor License Agreement (CLA) is signed.
• Pass all required CI checks.
• Submit small, focused PRs addressing a single concern/issue.
• Write a clear and descriptive title and summary.
• Include usage examples and benchmarks, if applicable.

Getting PRs Merged

A pull request is considered ready to merge when:

• It has received approval from Approvers or Maintainers.
• Major feedback has been resolved.
• It has been open for review for at least one working day.
• Trivial changes (typos, cosmetic, doc, etc.) don’t have to wait for one day.
• Urgent fixes can take exception as long as they have been actively communicated.

Any Maintainer can merge the PR once it is ready to merge. If a PR has been stuck, the owner should try to get people aligned by consolidating perspectives, tagging subdomain experts, reaching out to more people on the CNCF OpenTelemetry .NET Slack channel, or narrowing down the scope of the PR.

Design Choices

OpenTelemetry .NET follows the opentelemetry-specification and focuses on capabilities rather than structure compliance. Contributions should provide functionality and behavior that conforms to the specification while being flexible in terms of interface and structure.

Style Guide

OpenTelemetry .NET uses a .editorconfig file and StyleCop ruleset files to maintain a consistent coding style. The .editorconfig file is supported by all IDEs/editors mentioned above and does not affect the actual build of the project. The StyleCop ruleset files are used to configure the StyleCop.Analyzers which runs during the build. Breaking the rules will result in a build failure.

New Projects

New projects must:

• Use nullable reference types.
• Pass static analysis.
• Enable nullable context in public APIs manually.

New Code

New code files must enable nullable reference types manually in projects where it is not automatically enabled project-wide.

License Requirements

OpenTelemetry .NET is licensed under the Apache License, Version 2.0. When contributing files from other projects, ensure the license is permissive, the license is left intact, and the contribution is correctly attributed in the THIRD-PARTY-NOTICES.TXT file.

Available Commands

The project has the following available commands:

• dotnet build: Build the solution.
• dotnet pack: Build and create packages for the solution.
• dotnet run: Run the application using the current project as the entry point.
• dotnet test: Run all tests for the solution.
• dotnet publish: Publish the application for deployment.
• dotnet tool install --global OpenTelemetry.Cli: Install the OpenTelemetry CLI tool globally.
• OpenTelemetry.Cli collect --instrumentation=<instrumentation-name> --exporter=<exporter-name>: Collect and export data using the OpenTelemetry CLI tool.
• dotnet add package OpenTelemetry.Api: Add the OpenTelemetry API package to the project.
• dotnet add package OpenTelemetry.Instrumentation.<instrumentation-name>: Add the instrumentation package for a specific technology to the project.
• dotnet add package OpenTelemetry.Exporter.<exporter-name>: Add the exporter package for a specific backend to the project.

CI/CD Configurations

The project has a CI/CD configuration in the Dockerfile and docker-compose.yml. Use this information to guide your contributions.