-
Notifications
You must be signed in to change notification settings - Fork 502
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Documentation: Adds SDK guidelines (#1803)
* Documentation: Add sdk guidelines * Fixed spelling * Format fixes * Adding unit testing
- Loading branch information
Showing
1 changed file
with
23 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,23 @@ | ||
# SDK Design Guidelines | ||
|
||
## Public contract changes | ||
|
||
### API Review | ||
Public contract changes must go through an API review. Please create a github issue that explains the reason for the change and proposed design. For internal Microsoft engineers please schedule a meeting to review this with the SDK team. For external customers we will provide feedback to the github issue. | ||
|
||
### What is considered public contract? | ||
1. Public APIs | ||
2. Preview APIs | ||
3. Dependencies including nuget package version | ||
4. Behavioral changes. For example trying to convert the default serializer from Newtonsoft to System.Text.Json. | ||
|
||
### Unit testing | ||
All public APIs should support unit testing. Mocking should be supported on all public contracts where it is required to for unit testing scenarios. | ||
|
||
### Request options | ||
Request options should not be sealed. | ||
1. This allows internal teams to extend and add custom properties to request options which they can later access in lower layers of the SDK. | ||
2. Request options only has public properties, so there is no concern with users extending the type. | ||
|
||
### Central SDK | ||
The V3 SDK follow the [central SDK .NET guidelines](https://azure.github.io/azure-sdk/dotnet_introduction.html) where possible. V3 SDK was released before these guidelines existed so it does not have the same types. Consistency with the current V3 public API is more important than follow the central SDK .NET guidelines as it provides a better user experience. |