|
| 1 | +--- |
| 2 | +type: docs |
| 3 | +title: "Contributing to the .NET SDK" |
| 4 | +linkTitle: ".NET SDK" |
| 5 | +weight: 3000 |
| 6 | +description: Guidelines for contributing to the Dapr .NET SDK |
| 7 | +--- |
| 8 | + |
| 9 | +# Welcome! |
| 10 | +If you're reading this, you're likely interested in contributing to Dapr and/or the Dapr .NET SDK. Welcome to the project |
| 11 | +and thank you for your interest in contributing! |
| 12 | + |
| 13 | +Please review the documentation, familiarize yourself with what Dapr is and what it's seeking to accomplish and reach |
| 14 | +out on [Discord](https://bit.ly/dapr-discord). Let us know how you'd like to contribute and we'd be happy to chime in |
| 15 | +with ideas and suggestions. |
| 16 | + |
| 17 | +There are many ways to contribute to Dapr: |
| 18 | +- Submit bug reports for the [Dapr runtime](https://github.com/dapr/dapr/issues/new/choose) or the [Dapr .NET SDK](https://github.com/dapr/dotnet-sdk/issues/new/choose) |
| 19 | +- Propose new [runtime capabilities](https://github.com/dapr/proposals/issues/new/choose) or [SDK functionality](https://github.com/dapr/dotnet-sdk/issues/new/choose) |
| 20 | +- Improve the documentation in either the [larger Dapr project](https://github.com/dapr/docs) or the [Dapr .NET SDK specifically](https://github.com/dapr/dotnet-sdk/tree/master/daprdocs) |
| 21 | +- Add new or improve existing [components](https://github.com/dapr/components-contrib/) that implement the various building blocks |
| 22 | +- Augment the [.NET pluggable component SDK capabilities](https://github.com/dapr-sandbox/components-dotnet-sdk) |
| 23 | +- Improve the Dapr .NET SDK code base and/or fix a bug (detailed below) |
| 24 | + |
| 25 | +If you're new to the code base, please feel encouraged to ask in the #dotnet-sdk channel in Discord about how |
| 26 | +to implement changes or generally ask questions. You are not required to seek permission to work on anything, but do |
| 27 | +note that if an issue is assigned to someone, it's an indication that someone might have already started work on it. |
| 28 | +Especially if it's been a while since the last activity on that issue, please feel free to reach out and see if it's |
| 29 | +still something they're interested in pursuing or whether you can take over, and open a pull request with your |
| 30 | +implementation. |
| 31 | + |
| 32 | +If you'd like to assign yourself to an issue, respond to the conversation with "/assign" and the bot will assign you |
| 33 | +to it. |
| 34 | + |
| 35 | +We have labeled some issues as `good-first-issue` or `help wanted` indicating that these are likely to be small, |
| 36 | +self-contained changes. |
| 37 | + |
| 38 | +If you're not certain about your implementation, please create it as a draft pull request and solicit feedback |
| 39 | +from the [.NET maintainers](https://github.com/orgs/dapr/teams/maintainers-dotnet-sdk) by tagging |
| 40 | +`@dapr/maintainers-dotnet-sdk` and providing some context about what you need assistance with. |
| 41 | + |
| 42 | +# Contribution Rules and Best Practices |
| 43 | + |
| 44 | +When contributing to the [.NET SDK](https://github.com/dapr/dotnet-sdk) the following rules and best-practices should |
| 45 | +be followed. |
| 46 | + |
| 47 | +## Pull Requests |
| 48 | +Pull requests that contain only formatting changes are generally discouraged. Pull requests should instead seek to |
| 49 | +fix a bug, add new functionality, or improve on existing capabilities. |
| 50 | + |
| 51 | +Do aim to minimize the contents of your pull request to span only a single issue. Broad PRs that touch on a lot of files |
| 52 | +are not likely to be reviewed or accepted in a short timeframe. Accommodating many different issues in a single PR makes |
| 53 | +it hard to determine whether your code fully addresses the underlying issue(s) or not and complicates the code review. |
| 54 | + |
| 55 | +## Tests |
| 56 | +All pull requests should include unit and/or integration tests that reflect the nature of what was added or changed |
| 57 | +so it's clear that the functionality works as intended. Avoid using auto-generated tests that duplicate testing the |
| 58 | +same functionality several times. Rather, seek to improve code coverage by validating each possible path of your |
| 59 | +changes so future contributors can more easily navigate the contours of your logic and more readily identify limitations. |
| 60 | + |
| 61 | +## Examples |
| 62 | + |
| 63 | +The `examples` directory contains code samples for users to run to try out specific functionality of the various |
| 64 | +Dapr .NET SDK packages and extensions. When writing new and updated samples keep in mind: |
| 65 | + |
| 66 | +- All examples should be runnable on Windows, Linux, and MacOS. While .NET Core code is consistent among operating |
| 67 | +systems, any pre/post example commands should provide options through |
| 68 | +[tabpane]({{% ref "contributing-docs.md#tabbed-content" %}}) |
| 69 | +- Contain steps to download/install any required pre-requisites. Someone coming in with a fresh OS install should be |
| 70 | +able to start on the example and complete it without an error. Links to external download pages are fine. |
| 71 | + |
| 72 | +## Documentation |
| 73 | + |
| 74 | +The `daprdocs` directory contains the markdown files that are rendered into the [Dapr Docs](https://docs.dapr.io) website. When the |
| 75 | +documentation website is built this repo is cloned and configured so that its contents are rendered with the docs |
| 76 | +content. When writing docs keep in mind: |
| 77 | + |
| 78 | + - All rules in the [docs guide]({{% ref contributing-docs.md %}}) should be followed in addition to these. |
| 79 | + - All files and directories should be prefixed with `dotnet-` to ensure all file/directory names are globally |
| 80 | + - unique across all Dapr documentation. |
| 81 | + |
| 82 | +All pull requests should strive to include both XML documentation in the code clearly indicating what functionality |
| 83 | +does and why it's there as well as changes to the published documentation to clarify for other developers how your change |
| 84 | +improves the Dapr framework. |
| 85 | + |
| 86 | +## GitHub Dapr Bot Commands |
| 87 | + |
| 88 | +Checkout the [daprbot documentation](https://docs.dapr.io/contributing/daprbot/) for Github commands you can run in this repo for common tasks. For example, |
| 89 | +you can comment `/assign` on an issue to assign it to yourself. |
| 90 | + |
| 91 | +## Commit Sign-offs |
| 92 | +All code submitted to the Dapr .NET SDK must be signed off by the developer authoring it. This means that every |
| 93 | +commit must end with the following: |
| 94 | +> Signed-off-by: First Last <flast@example.com> |
| 95 | +
|
| 96 | +The name and email address must match the registered GitHub name and email address of the user committing the changes. |
| 97 | +We use a bot to detect this in pull requests and we will be unable to merge the PR if this check fails to validate. |
| 98 | + |
| 99 | +If you notice that a PR has failed to validate because of a failed DCO check early on in the PR history, please consider |
| 100 | +squashing the PR locally and resubmitting to ensure that the sign-off statement is included in the commit history. |
| 101 | + |
| 102 | +# Languages, Tools and Processes |
| 103 | +All source code in the Dapr .NET SDK is written in C# and targets the latest language version available to the earliest |
| 104 | +supported .NET SDK. As of v1.16, this means that both .NET 8 and .NET 9 are supported. The latest language version available |
| 105 | +is [C# version 12](https://learn.microsoft.com/dotnet/csharp/whats-new/csharp-version-history#c-version-12) |
| 106 | + |
| 107 | +Contributors are welcome to use whatever IDE they're most comfortable developing in, but please do not submit |
| 108 | +IDE-specific preference files along with your contributions as these will be rejected. |
0 commit comments