The OpenTelemetry .NET 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
Slack.
Anyone may contribute but there are benefits of being a member of our community.
See the community membership
document
on how to become a
Member,
Approver
and
Maintainer.
Find a buddy and get started quickly
If you are looking for someone to help you find a starting point and be a
resource for your first contribution, join our Slack channel and find a buddy!
- Create your CNCF Slack account and join the
otel-dotnet channel.
- Post in the room with an introduction to yourself, what area you are
interested in (check issues marked with help
wanted),
and say you are looking for a buddy. We will match you with someone who has
experience in that area.
Your OpenTelemetry buddy is your resource to talk to directly on all aspects of
contributing to OpenTelemetry: providing context, reviewing PRs, and helping
those get merged. Buddies will not be available 24/7, but are committed to
responding during their normal working hours.
Development Environment
You can contribute to this project from a Windows, macOS, or Linux machine.
On all platforms, the minimum requirements are:
Linux or MacOS
- Visual Studio 2022+ for Mac or Visual Studio Code
Mono might be required by your IDE but is not required by this project. This is
because unit tests targeting .NET Framework (i.e: net462) are disabled outside
of Windows.
Windows
- Visual Studio 2022+ or Visual Studio Code
- .NET Framework 4.6.2+
Public API validation
It is critical to NOT make breaking changes to public APIs which have been
released in stable builds. We also strive to keep a minimal public API surface.
This repository is using
Microsoft.CodeAnalysis.PublicApiAnalyzers
and Package
validation
to validate public APIs.
Microsoft.CodeAnalysis.PublicApiAnalyzers will validate public API
changes/additions against a set of “public API files” which capture the
shipped/unshipped public APIs. These files must be maintained manually (not
recommended) or by using tooling/code fixes built into the package (see below
for details).
Public API files are also used to perform public API reviews by repo
approvers/maintainers before releasing stable builds.
Package validation will validate public API changes/additions against
previously released NuGet packages.
This is performed automatically by the build/CI
package-validation
workflow.
By default package validation is NOT run for local builds. To enable
package validation in local builds set the EnablePackageValidation property
to true in
Common.prod.props
(please do not check in this change).
Working with Microsoft.CodeAnalysis.PublicApiAnalyzers
Update public API files when writing code
IntelliSense
will suggest
modifications
to the PublicAPI.Unshipped.txt file when you make changes. After reviewing
these changes, ensure they are reflected across all targeted frameworks. You can
do this by:
Using the “Fix all occurrences in Project” feature in Visual Studio.
Manually cycling through each framework using Visual Studio’s target framework
dropdown (in the upper right corner) and applying the IntelliSense
suggestions.
[!IMPORTANT]
Do NOT modify PublicAPI.Shipped.txt files. New features and bug fixes
SHOULD only require changes to PublicAPI.Unshipped.txt files. If you
have to modify a “shipped” file it likely means you made a mistake and broke a
stable API. Typically only maintainers modify the PublicAPI.Shipped.txt file
while performing stable releases. If you need help reach out to an approver or
maintainer on Slack or open a draft PR.
Enable public API validation in new projects
If you are NOT using experimental APIs:
- If your API is the same across all target frameworks:
- If your APIs differ between target frameworks:
- Place the shared APIs in
.publicApi/PublicAPI.Shipped.txt and
.publicApi/PublicAPI.Unshipped.txt.
- Create framework-specific files for API differences (e.g.,
.publicApi/net462/PublicAPI.Shipped.txt and
.publicApi/net462/PublicAPI.Unshipped.txt).
If you are using experimental APIs:
Example folder structure can be found
here.
Pull Requests
How to create pull requests
Everyone is welcome to contribute code to opentelemetry-dotnet via GitHub pull
requests (PRs).
To create a new PR, fork the project on GitHub and clone the upstream repo:
git clone https://github.com/open-telemetry/opentelemetry-dotnet.git
Navigate to the repo root:
cd opentelemetry-dotnet
Add your fork as an origin:
git remote add fork https://github.com/YOUR_GITHUB_USERNAME/opentelemetry-dotnet.git
Run tests:
dotnet test
If you made changes to the Markdown documents (*.md files), install the latest
markdownlint-cli and run:
markdownlint .
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
Open a pull request against the main opentelemetry-dotnet repo.
Tips and best practices for pull requests
- If the PR is not ready for review, please mark it as
draft.
- Make sure CLA is signed and all required CI checks are clear.
- Submit small, focused PRs addressing a single concern/issue.
- Make sure the PR title reflects the contribution.
- Write a summary that helps understand the change.
- Include usage examples in the summary, where applicable.
- Include benchmarks (before/after) in the summary, for contributions that are
performance enhancements.
- We are open to bot generated PRs or AI/LLM assisted PRs. Actually, we are
using
dependabot
to automate the security updates. However, if you use bots to generate spam
PRs (e.g. incorrect, noisy, non-improvements, unintelligible, trying to sell
your product, etc.), we might close the PR right away with a warning, and if
you keep doing so, we might block your user account.
How to get pull requests merged
A PR is considered to be ready to merge when:
Any maintainer can merge PRs once they are ready to merge however
maintainers might decide to wait on merging changes until there are more
approvals and/or dicussion, or based on other factors such as release timing and
risk to users. For example if a stable release is planned and a new change is
introduced adding public API(s) or behavioral changes it might be held until the
next alpha/beta release.
If a PR has become stuck (e.g. there is a lot of debate and people couldn’t
agree on the direction), the owner should try to get people aligned by:
- Consolidating the perspectives and putting a summary in the PR. It is
recommended to add a link into the PR description, which points to a comment
with a summary in the PR conversation.
- Tagging subdomain experts (by looking at the change history) in the PR asking
for suggestion.
- Reaching out to more people on the CNCF OpenTelemetry .NET Slack
channel.
- Stepping back to see if it makes sense to narrow down the scope of the PR or
split it up.
- If none of the above worked and the PR has been stuck for more than 2 weeks,
the owner should bring it to the OpenTelemetry .NET SIG
meeting.
Design choices
As with other OpenTelemetry clients, opentelemetry-dotnet follows the
opentelemetry-specification.
It’s especially valuable to read through the library
guidelines.
Focus on capabilities not structural compliance
OpenTelemetry is an evolving specification, one where the desires and use cases
are clear, but the method to satisfy those uses cases are not.
As such, contributions should provide functionality and behavior that conforms
to the specification, but the interface and structure is flexible.
It is preferable to have contributions follow the idioms of the language rather
than conform to specific API names or argument patterns in the spec.
For a deeper discussion, see this spec
issue.
Style guide
This project includes a .editorconfig file which is
supported by all the IDEs/editors mentioned above. It works with the IDE/editor
only and does not affect the actual build of the project.
This repository also includes StyleCop ruleset files under the ./build folder.
These files are used to configure the StyleCop.Analyzers which runs during
build. Breaking the rules will result in a build failure.
New projects
New projects are required to:
Use nullable reference
types.
This should be enabled automatically via
Common.props.
New project MUST NOT disable this.
Pass static
analysis.
New projects MUST enable static analysis by specifying
<AnalysisLevel>latest-all</AnalysisLevel> in the project file (.csproj).
[!NOTE]
There are other project-level features enabled automatically via
Common.props
new projects must NOT manually override these settings.
License requirements
OpenTelemetry .NET is licensed under the Apache License, Version
2.0.
Copying files from other projects
OpenTelemetry .NET uses some files from other projects, typically where a binary
distribution does not exist or would be inconvenient.
The following rules must be followed for PRs that include files from another
project:
The license of the file is
permissive.
The license of the file is left intact.
The contribution is correctly attributed in the 3rd party
notices file in the repository, as needed.
See
EnvironmentVariablesExtensions.cs
for an example of a file copied from another project and attributed in the 3rd
party notices file.
