Skip to content

Commit b048d18

Browse files
RogerBarretomusale
authored andcommitted
.Net: ADR Samples Contribution Guidelines (microsoft#10526)
### Motivation and Context - Partially Resolves microsoft#10168
1 parent bbf5137 commit b048d18

File tree

1 file changed

+93
-0
lines changed

1 file changed

+93
-0
lines changed
+93
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
---
2+
# These are optional elements. Feel free to remove any of them.
3+
status: proposed
4+
contact: rogerbarreto
5+
date: 2025-02-11
6+
deciders: markwallace, sergey, dmytro, weslie, evan, shawn
7+
---
8+
9+
# Structured Concepts
10+
11+
## Context and Problem Statement
12+
13+
Currently, the Concepts project has grown considerably, with many samples that do not consistently follow a structured pattern or guideline.
14+
15+
A revisit of our sample patterns in favor of key drivers needs to be considered.
16+
17+
This ADR starts by suggesting rules we might follow to keep new concepts following good patterns that make them easy to comprehend, find, and descriptive.
18+
19+
The Semantic Kernel audience can vary greatly—from pro-devs, beginners, and non-developers. We understand that making sure examples and guidelines are as straightforward as possible is of our highest priority.
20+
21+
### Decision Drivers
22+
23+
- Easy to find
24+
- Easy to understand
25+
- Easy to set up
26+
- Easy to execute
27+
28+
The above drivers focus on ensuring that we follow good practices, patterns, and a structure for our samples, guaranteeing proper documentation, simplification of code for easier understanding, as well as the usage of descriptive classes, methods, and variables.
29+
30+
We also understand how important it is to ensure our samples are copy-and-paste friendly (work "as is"), being as frictionless as possible.
31+
32+
## Solution
33+
34+
Applying a set of easy-to-follow guidelines and good practices to the Concepts project will help maintain a good collection of samples that are easy to find, understand, set up, and execute.
35+
36+
This guideline will be applied for any maintenance or newly added samples to the Concepts project. The contents may be added to a new CONTRIBUTING.md file in the Concepts project.
37+
38+
> [!NOTE]
39+
> Rules/Conventions that are already ensured by analyzers are not mentioned in the list below.
40+
41+
## Rules
42+
43+
### Sample Classes
44+
45+
Each class in the Concepts project MUST have an xmldoc description of what is being sampled, with clear information on what is being sampled.
46+
47+
✅ DO have xmldoc description detailing what is being sampled.
48+
49+
✅ DO have xmldoc remarks for the required packages.
50+
51+
✅ CONSIDER using xmldoc remarks for additional information.
52+
53+
❌ AVOID using generic descriptions.
54+
55+
✅ DO name classes with at least two words, separated by an underscore `First_Second_Third_Fourth`.
56+
57+
✅ DO name classes with the `First` word reserved for the given concept or provider name (e.g., `OpenAI_ChatCompletion`).
58+
59+
When the file has examples for a specific `<provider>`, it should start with the `<provider>` as the first word. `<provider>` here can also include runtime, platform, protocol, or service names.
60+
61+
✅ CONSIDER naming `Second` and later words to create the best grouping for examples,
62+
e.g., `AzureAISearch_VectorStore_ConsumeFromMemoryStore`.
63+
64+
✅ CONSIDER naming when there are more than two words, using a left-to-right grouping,
65+
e.g., `AzureAISearch_VectorStore_ConsumeFromMemoryStore`: for `AzureAISearch` within `VectorStore` grouping, there's a `ConsumeFromMemoryStore` example.
66+
67+
### Sample Methods
68+
69+
✅ DO have an xmldoc description detailing what is being sampled when the class has more than one sample method.
70+
71+
✅ DO have descriptive method names limited to five words, separated by an underscore,
72+
e.g., `[Fact] public Task First_Second_Third_Fourth_Fifth()`.
73+
74+
❌ DO NOT use `Async` suffix for Tasks.
75+
76+
❌ AVOID using parameters in the method signature.
77+
78+
❌ DO NOT have more than 3 samples in a single class. Split the samples into multiple classes when needed.
79+
80+
### Code
81+
82+
✅ DO keep code clear and concise. For the most part, variable names and APIs should be self-explanatory.
83+
84+
✅ CONSIDER commenting the code for large sample methods.
85+
86+
❌ DO NOT use acronyms or short names for variables, methods, or classes.
87+
88+
❌ AVOID any references to common helper classes or methods that are not part of the sample file,
89+
e.g., avoid methods like `BaseTest.OutputLastMessage`.
90+
91+
## Decision Outcome
92+
93+
TBD

0 commit comments

Comments
 (0)