dotnet-monitor/CONTRIBUTING.md

Contribution to .NET Monitor

You can contribute to .NET Monitor with issues and PRs. Simply filing issues for problems you encounter is a great way to contribute. Contributing implementations is greatly appreciated.

Reporting Issues

We always welcome bug reports, proposals and overall feedback. Here are a few tips on how you can make reporting your issue as effective as possible.

Finding Existing Issues

Before filing a new issue, please search our open issues to check if it already exists.

If you do find an existing issue, please include your own feedback in the discussion. Do consider upvoting (👍 reaction) the original post, as this helps us prioritize popular issues in our backlog.

Writing a Good Bug Report

Good bug reports make it easier for maintainers to verify and root cause the underlying problem. The better a bug report, the faster the problem will be resolved. Ideally, a bug report should contain the following information:

• A high-level description of the problem.
• A minimal reproduction, i.e. the smallest size of code/configuration required to reproduce the wrong behavior.
• A description of the expected behavior, contrasted with the actual behavior observed.
• Information on the environment: OS/distribution, CPU arch, SDK version, etc.
• Additional information, e.g. is it a regression from previous versions? are there any known workarounds?

DOs and DON'Ts

Please do:

• DO follow our coding style.
• DO include tests when adding new features. When fixing bugs, start with adding a test that highlights how the current behavior is broken.
• DO keep the discussions focused. When a new or related topic comes up it's often better to create a new issue than to side track the discussion.
• DO feel free to blog, tweet, or share anywhere else about your contributions!

Please do not:

• DON'T make PRs for style changes.
• DON'T surprise us with big pull requests. For large changes, create a new discussion so we can agree on a direction before you invest a large amount of time. For bug fixes, create an issue.
• DON'T commit code that you didn't write. If you find code that you think is a good fit to add to .NET Monitor, file an issue and start a discussion before proceeding.
• DON'T submit PRs that alter licensing related files or headers. If you believe there's a problem with them, file an issue and we'll be happy to discuss it.

Suggested Workflow

We use and recommend the following workflow:

1. Create an issue for your work.
   • You can skip this step for trivial changes.
   • Reuse an existing issue on the topic, if there is one.
   • Get agreement from the team and the community that your proposed change is a good one.
   • Clearly state that you are going to take on implementing it, if that's the case. You can request that the issue be assigned to you. Note: The issue filer and the implementer don't have to be the same person.
2. Create a personal fork of the repository on GitHub (if you don't already have one).
3. In your fork, create a branch off of main (git checkout -b mybranch).
   • Name the branch so that it clearly communicates your intentions, such as issue-123 or githubhandle-issue.
   • Branches are useful since they isolate your changes from incoming changes from upstream. They also enable you to create multiple PRs from the same fork.
4. Make and commit your changes to your branch.
5. Add new tests corresponding to your change, if applicable.
6. Build the repository with your changes.
   • Make sure that the builds are clean.
   • Make sure that the tests are all passing, including your new tests.
7. Create a pull request (PR) against the dotnet/dotnet-monitor repository's main branch.
   • State in the description what issue or improvement your change is addressing.
   • Check if all the tests are passing.
8. Wait for feedback or approval of your changes from the team.
9. When the team has signed off, and all checks are green, your PR will be merged.
   • The next official build will include your change.
   • You can delete the branch you used for making the change.

Contributor License Agreement

You must sign a .NET Foundation Contribution License Agreement (CLA) before your PR will be merged. This is a one-time requirement for projects in the .NET Foundation. You can read more about Contribution License Agreements (CLA) on Wikipedia.

The agreement: net-foundation-contribution-license-agreement.pdf

You don't have to do this up-front. You can simply clone, fork, and submit your pull-request as usual. When your pull-request is created, it is classified by a CLA bot. If the change is trivial (for example, you just fixed a typo), then the PR is labelled with cla-not-required. Otherwise it's classified as cla-required. Once you signed a CLA, the current and all future pull-requests will be labelled as cla-signed.

File Headers

Please use the following file header for new files.

// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

PR - CI Process

The dotnet continuous integration (CI) system will automatically perform the required builds and run tests (including the ones you are expected to run) for PRs. Builds and test runs must be clean.

If the CI build fails for any reason, the PR issue will be updated with a link that can be used to determine the cause of the failure.

PR Feedback

Microsoft team and community members will provide feedback on your change. Community feedback is highly valued. You will often see the absence of team feedback if the community has already provided good review feedback.

One or more Microsoft team members will review every PR prior to merge. That means that the PR will be merged once the feedback is resolved. "LGTM" == "looks good to me".

There are lots of thoughts and approaches for how to efficiently discuss changes. It is best to be clear and explicit with your feedback. Please be patient with people who might not understand the finer details about your approach to feedback.

Stale PR Policy

In an effort to prevent pull requests from becoming stale, the dotnet-monitor team will comment on pull requests that haven't had any activity in the last 4 weeks to ensure they are still under active development. After this point, if there are no updates on the pull request, the dotnet-monitor team will close the pull request 6 weeks after the notification. In the event that your pull request is closed, please feel free to re-open the pull request in the future to continue the review process, or open a new pull request with a link to the closed one.