SDK contributing guide

• 1: Contributing to the .NET SDK
• 2: Contributing to the Go SDK
• 3: Contributing to the Java SDK
• 4: Contributing to the JavaScript SDK
• 5: Contributing to the Python SDK
• 6: Contributing to the Rust SDK

1 - Contributing to the .NET SDK

Welcome!

If you’re reading this, you’re likely interested in contributing to Dapr and/or the Dapr .NET SDK. Welcome to the project and thank you for your interest in contributing!

Please review the documentation, familiarize yourself with what Dapr is and what it’s seeking to accomplish and reach out on Discord. Let us know how you’d like to contribute and we’d be happy to chime in with ideas and suggestions.

There are many ways to contribute to Dapr:

• Submit bug reports for the Dapr runtime or the Dapr .NET SDK
• Propose new runtime capabilities or SDK functionality
• Improve the documentation in either the larger Dapr project or the Dapr .NET SDK specifically
• Add new or improve existing components that implement the various building blocks
• Augment the .NET pluggable component SDK capabilities
• Improve the Dapr .NET SDK code base and/or fix a bug (detailed below)

If you’re new to the code base, please feel encouraged to ask in the #dotnet-sdk channel in Discord about how to implement changes or generally ask questions. You are not required to seek permission to work on anything, but do note that if an issue is assigned to someone, it’s an indication that someone might have already started work on it. 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 still something they’re interested in pursuing or whether you can take over, and open a pull request with your implementation.

If you’d like to assign yourself to an issue, respond to the conversation with “/assign” and the bot will assign you to it.

We have labeled some issues as good-first-issue or help wanted indicating that these are likely to be small, self-contained changes.

If you’re not certain about your implementation, please create it as a draft pull request and solicit feedback from the .NET maintainers by tagging @dapr/maintainers-dotnet-sdk and providing some context about what you need assistance with.

Contribution Rules and Best Practices

When contributing to the .NET SDK the following rules and best-practices should be followed.

Pull Requests

Pull requests that contain only formatting changes are generally discouraged. Pull requests should instead seek to fix a bug, add new functionality, or improve on existing capabilities.

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 are not likely to be reviewed or accepted in a short timeframe. Accommodating many different issues in a single PR makes it hard to determine whether your code fully addresses the underlying issue(s) or not and complicates the code review.

Tests

All pull requests should include unit and/or integration tests that reflect the nature of what was added or changed so it’s clear that the functionality works as intended. Avoid using auto-generated tests that duplicate testing the same functionality several times. Rather, seek to improve code coverage by validating each possible path of your changes so future contributors can more easily navigate the contours of your logic and more readily identify limitations.

Examples

The examples directory contains code samples for users to run to try out specific functionality of the various Dapr .NET SDK packages and extensions. When writing new and updated samples keep in mind:

• All examples should be runnable on Windows, Linux, and MacOS. While .NET Core code is consistent among operating systems, any pre/post example commands should provide options through tabpane
• Contain steps to download/install any required pre-requisites. Someone coming in with a fresh OS install should be able to start on the example and complete it without an error. Links to external download pages are fine.

Documentation

The daprdocs directory contains the markdown files that are rendered into the Dapr Docs website. When the documentation website is built this repo is cloned and configured so that its contents are rendered with the docs content. When writing docs keep in mind:

• All rules in the docs guide should be followed in addition to these.
• All files and directories should be prefixed with dotnet- to ensure all file/directory names are globally
• unique across all Dapr documentation.

All pull requests should strive to include both XML documentation in the code clearly indicating what functionality does and why it’s there as well as changes to the published documentation to clarify for other developers how your change improves the Dapr framework.

GitHub Dapr Bot Commands

Checkout the daprbot documentation for Github commands you can run in this repo for common tasks. For example, you can comment /assign on an issue to assign it to yourself.

Commit Sign-offs

All code submitted to the Dapr .NET SDK must be signed off by the developer authoring it. This means that every commit must end with the following:

Signed-off-by: First Last flast@example.com

The name and email address must match the registered GitHub name and email address of the user committing the changes. 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.

If you notice that a PR has failed to validate because of a failed DCO check early on in the PR history, please consider squashing the PR locally and resubmitting to ensure that the sign-off statement is included in the commit history.

Languages, Tools and Processes

All source code in the Dapr .NET SDK is written in C# and targets the latest language version available to the earliest supported .NET SDK. As of v1.15, this means that because .NET 6 is still supported, the latest language version available is C# version 10.

As of v1.15, the following versions of .NET are supported:

Contributors are welcome to use whatever IDE they’re most comfortable developing in, but please do not submit IDE-specific preference files along with your contributions as these will be rejected.

2 - Contributing to the Go SDK

When contributing to the Go SDK the following rules and best-practices should be followed.

Examples

The examples directory contains code samples for users to run to try out specific functionality of the various Go SDK packages and extensions. When writing new and updated samples keep in mind:

• All examples should be runnable on Windows, Linux, and MacOS. While Go code is consistent among operating systems, any pre/post example commands should provide options through tabpane
• Contain steps to download/install any required pre-requisites. Someone coming in with a fresh OS install should be able to start on the example and complete it without an error. Links to external download pages are fine.

Docs

The daprdocs directory contains the markdown files that are rendered into the Dapr Docs website. When the documentation website is built this repo is cloned and configured so that its contents are rendered with the docs content. When writing docs keep in mind:

• All rules in the docs guide should be followed in addition to these.
• All files and directories should be prefixed with go- to ensure all file/directory names are globally unique across all Dapr documentation.

3 - Contributing to the Java SDK

When contributing to the Java SDK the following rules and best-practices should be followed.

Examples

The examples directory contains code samples for users to run to try out specific functionality of the various Java SDK packages and extensions. When writing new and updated samples keep in mind:

• All examples should be runnable on Windows, Linux, and MacOS. While Java code is consistent among operating systems, any pre/post example commands should provide options through tabpane
• Contain steps to download/install any required pre-requisites. Someone coming in with a fresh OS install should be able to start on the example and complete it without an error. Links to external download pages are fine.

Docs

The daprdocs directory contains the markdown files that are rendered into the Dapr Docs website. When the documentation website is built, this repo is cloned and configured so that its contents are rendered with the docs content. When writing docs, keep in mind:

• All rules in the docs guide should be followed in addition to these.
• All files and directories should be prefixed with java- to ensure all file/directory names are globally unique across all Dapr documentation.

Github Dapr Bot Commands

Checkout the daprbot documentation for Github commands you can run in this repo for common tasks. For example, you can run the /assign (as a comment on an issue) to assign the issue to yourself.

4 - Contributing to the JavaScript SDK

When contributing to the JavaScript SDK the following rules and best-practices should be followed.

💡 You can run npm pretty-fix to run prettier on all your files

Commit Guidelines

The Dapr Javascript SDK uses the Conventional Commits specification. The automatic changelog tool uses these to automatically generate a changelog based on the commit messages. Here’s a guide to writing a commit message to allow this:

Format

type(scope)!: subject

• type: the type of the commit is one of the following:

  • feat: new features.
  • fix: bug fixes.
  • docs: documentation changes.
  • refactor: refactor of a particular code section without introducing new features or bug fixes.
  • style: code style improvements.
  • perf: performance improvements.
  • test: changes to the test suite.
  • ci: changes to the CI system.
  • build: changes to the build system (we don’t yet have one so this shouldn’t apply).
  • chore: for other changes that don’t match previous types. This doesn’t appear in the changelog.

• scope: section of the codebase that the commit makes changes to. If it makes changes to many sections, or if no section in particular is modified, leave blank without the parentheses. Examples:

  • Commit that adds a test:

  test(actors): add an actor test
  

  • Commit that changes many things at once:

  style: adopt eslint
  

  For changes to examples, the scope should be the example name with the examples/ prefix:

  • ❌ fix(agnoster): commit subject
  • ✅ fix(examples/http/actor): commit subject

• !: this goes after the scope (or the type if scope is empty), to indicate that the commit introduces breaking changes.

  Optionally, you can specify a message that the changelog tool will display to the user to indicate what’s changed and what they can do to deal with it. You can use multiple lines to type this message; the changelog parser will keep reading until the end of the commit message or until it finds an empty line.

  Example (made up):

  style(agnoster)!: change dirty git repo glyph
  
  BREAKING CHANGE: the glyph to indicate when a git repository is dirty has
  changed from a Powerline character to a standard UTF-8 emoji.
  
  Fixes #420
  
  Co-authored-by: Username <email>
  

• subject: a brief description of the changes. This will be displayed in the changelog. If you need to specify other details you can use the commit body but it won’t be visible.

  Formatting tricks: the commit subject may contain:

  • Links to related issues or PRs by writing #issue. This will be highlighted by the changelog tool:

    feat(archlinux): add support for aura AUR helper (#9467)
    

  • Formatted inline code by using backticks: the text inbetween backticks will also be highlighted by the changelog tool:

    feat(shell-proxy): enable unexported `DEFAULT_PROXY` setting (#9774)
    

Style

Try to keep the first commit line short. This is harder to do using this commit style but try to be concise and if you need more space, you can use the commit body. Try to make sure that the commit subject is clear and precise enough that users will know what change by just looking at the changelog.

Github Dapr Bot Commands

Checkout the daprbot documentation for Github commands you can run in this repo for common tasks. For example, you can run the /assign (as a comment on an issue) to assign issues to a user or group of users.

Coding Rules

To ensure consistency throughout the source code, keep these rules in mind as you are working:

• All features or bug fixes must be tested by one or more specs (unit-tests).
• All public API methods must be documented.
• We follow ESLint RecommendedRules.

Examples

The examples directory contains code samples for users to run to try out specific functionality of the various JavaScript SDK packages and extensions. When writing new and updated samples keep in mind:

• All examples should be runnable on Windows, Linux, and MacOS. While JavaScript code is consistent among operating systems, any pre/post example commands should provide options through tabpane.
• Contain steps to download/install any required pre-requisites. Someone coming in with a fresh OS install should be able to start on the example and complete it without an error. Links to external download pages are fine.

Docs

The daprdocs directory contains the markdown files that are rendered into the Dapr Docs website. When the documentation website is built, this repo is cloned and configured so that its contents are rendered with the docs content. When writing docs, keep in mind:

• All rules in the docs guide should be followed in addition to these.
• All files and directories should be prefixed with js- to ensure all file/directory names are globally unique across all Dapr documentation.

5 - Contributing to the Python SDK

When contributing to the Python SDK the following rules and best-practices should be followed.

Examples

The examples directory contains code samples for users to run to try out specific functionality of the various Python SDK packages and extensions. When writing new and updated samples keep in mind:

• All examples should be runnable on Windows, Linux, and MacOS. While Python code is consistent among operating systems, any pre/post example commands should provide options through tabpane
• Contain steps to download/install any required pre-requisites. Someone coming in with a fresh OS install should be able to start on the example and complete it without an error. Links to external download pages are fine.

Docs

The daprdocs directory contains the markdown files that are rendered into the Dapr Docs website. When the documentation website is built this repo is cloned and configured so that its contents are rendered with the docs content. When writing docs keep in mind:

• All rules in the docs guide should be followed in addition to these.
• All files and directories should be prefixed with python- to ensure all file/directory names are globally unique across all Dapr documentation.

Github Dapr Bot Commands

Checkout the daprbot documentation for Github commands you can run in this repo for common tasks. For example, you can run the /assign (as a comment on an issue) to assign issues to a user or group of users.

6 - Contributing to the Rust SDK

When contributing to the Rust SDK the following rules and best-practices should be followed.

Examples

The examples directory contains code samples for users to run to try out specific functionality of the various Rust SDK packages and extensions. It also hosts component examples used for validation. When writing new and updated samples keep in mind:

• All examples should be runnable on Windows, Linux, and MacOS. While Rust code is consistent among operating systems aside from minor OS-feature gating, any pre/post example commands should provide options through tabpane
• Contain steps to download/install any required pre-requisites. Someone coming in with a fresh OS install should be able to start on the example and complete it without an error. Links to external download pages are fine.
• Examples should be pass validation and include mechanical markdown steps and be added to the validation workflow TBA

Docs

The daprdocs directory contains the markdown files that are rendered into the Dapr Docs website. When the documentation website is built this repo is cloned and configured so that its contents are rendered with the docs content. When writing docs keep in mind:

• All rules in the docs guide should be followed in addition to these.
• All files and directories should be prefixed with rust- to ensure all file/directory names are globally unique across all Dapr documentation.

Update Protobufs

To pull the protobufs from the dapr/dapr repo you can run the script in the repo root like so:

./update-protos.sh

By default, the script fetches the latest proto updates from the master branch of the Dapr repository. If you need to choose a specific release or version, use the -v flag:

./update-protos.sh -v v1.13.0