Skip to content

Latest commit

 

History

History
352 lines (263 loc) · 14.5 KB

CONTRIBUTING.md

File metadata and controls

352 lines (263 loc) · 14.5 KB
Raw

Contributing to opentelemetry-dotnet

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!

  1. Create your CNCF Slack account and join the otel-dotnet channel.
  2. 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:

  • Git client and command line tools

  • .NET SDK (latest stable version)

    [!NOTE] At times a pre-release version of the .NET SDK may be required to build code in this repository. Check global.json to verify the current required version.

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

  1. If you are NOT using experimental APIs:

    • If your API is the same across all target frameworks:
      • You only need two files: .publicApi/PublicAPI.Shipped.txt and .publicApi/PublicAPI.Unshipped.txt.
    • 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).

  2. If you are using experimental APIs:

    • Follow the rules above, but create an additional layer in your folder structure:
      • For stable APIs: .publicApi/Stable/*.
      • For experimental APIs: .publicApi/Experimental/*.
    • The Experimental folder should contain APIs that are public only in pre-release builds. Typically the Experimental folder only contains PublicAPI.Unshipped.txt files as experimental APIs are never shipped stable.

    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:

  • It has received approval from Approvers. / Maintainers.
  • Major feedback/comments are resolved.
  • It has been open for review for at least one working day. This gives people reasonable time to review.
    • Trivial change (typo, cosmetic, doc, etc.) doesn't have to wait for one day.
    • Urgent fix can take exception as long as it has been actively communicated.

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.

New code

New code files MUST enable nullable reference types manually in projects where it is not automatically enabled project-wide. This is done by specifying #nullable enable towards the top of the file (usually after the copyright header). We are currently working towards enabling nullable context in every project by updating code as it is worked on, this requirement is to make sure the surface area of code needing updates is shrinking and not expanding.

Note

The first time a project is updated to use nullable context in public APIs some housekeeping needs to be done in public API definitions (.publicApi folder). This can be done automatically via a code fix offered by the public API analyzer.

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.