Skip to content

Commit b16eadd

Browse files
seesharprunseesharprun
authored
Enhance copilot instructions for Markdown in Azure Cosmos DB
1 parent fbf3b4b commit b16eadd

File tree

2 files changed

+340
-0
lines changed

2 files changed

+340
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,4 +54,75 @@ Below are instructions specific to this repository. These may be updated by repo
5454

5555
<!--- Add additional repository level instructions below. Do NOT update this line or above. --->
5656

57+
### Content structure
5758

59+
### Content completeness
60+
61+
- Procedures must include all steps - check for missing prerequisites or follow-up actions
62+
- Code samples must be complete and runnable - no placeholder comments like `// add code here`
63+
64+
### Alert usage
65+
66+
- Limit alerts to one or two per article
67+
- Never place multiple notes consecutively
68+
- Use the correct alert type:
69+
- `[!NOTE]` - Information the user should notice even if skimming
70+
- `[!TIP]` - Optional information to help a user be more successful
71+
- `[!IMPORTANT]` - Essential information required for user success
72+
- `[!WARNING]` - Dangerous certain consequences of an action
73+
74+
### Markdown Formatting
75+
76+
#### Headings
77+
78+
- Each file must have exactly one H1 heading
79+
- Do not skip heading levels (H2 to H4 without H3)
80+
81+
#### Code blocks
82+
83+
- Always specify the language identifier for syntax highlighting
84+
- Use `azurecli` for Azure CLI commands
85+
- Use `bash` for generic command line instructions
86+
87+
#### Tables
88+
89+
- Use exactly `| --- |` for column separators, not `|--------|`
90+
- For alignment: `| :-- |` (left), `| :--: |` (center), `| --: |` (right)
91+
- Empty first column headers are allowed when first column values are bolded
92+
93+
### Writing Style
94+
95+
#### Word choice
96+
97+
| Use | Instead of |
98+
| --- | --- |
99+
| use | utilize |
100+
| remove | eliminate |
101+
| because | since (when meaning "because") |
102+
| to | in order to |
103+
104+
#### Input-agnostic verbs
105+
106+
Use verbs that work for all input methods (mouse, keyboard, touch):
107+
108+
| Use | Instead of |
109+
| --- | --- |
110+
| Select | Click |
111+
| Choose | Tap |
112+
| Enter | Type |
113+
114+
#### Bias-free language
115+
116+
- Use people-first language: "users who are blind" not "blind users"
117+
- Use gender-neutral terms: "sales representative" not "salesman"
118+
- Show diverse perspectives in examples
119+
120+
### Review Style
121+
122+
When providing feedback:
123+
124+
- Be specific and actionable - explain what to change and why
125+
- Acknowledge good patterns when you see them
126+
- Ask clarifying questions when intent is unclear
127+
- Prioritize terminology issues and technical accuracy
128+
- Focus on improvements that help readers succeed

‎.github/instructions/cosmos-db.instructions.md‎

Lines changed: 269 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,269 @@
1+
---
2+
description: Code review and content authoring guidelines for Azure Cosmos DB documentation
3+
applyTo: "articles/cosmos-db/**/*.md"
4+
---
5+
6+
# Azure Cosmos DB documentation guidelines
7+
8+
## Terminology
9+
10+
Product naming and branding rules for prose text in documentation.
11+
12+
### Product naming
13+
14+
| Correct | Incorrect |
15+
| --- | --- |
16+
| Azure Cosmos DB | Cosmos DB |
17+
| Azure Cosmos DB | Azure Cosmos DB for NoSQL |
18+
| Azure Cosmos DB | Cosmos DB for NoSQL |
19+
20+
Always use "Azure Cosmos DB" as the full product name in prose text.
21+
22+
### Exceptions
23+
24+
The following metadata fields are acceptable and should not be changed:
25+
26+
- `ms.service: azure-cosmos-db` - Microsoft Learn taxonomy value
27+
- `ms.subservice: nosql` - Microsoft Learn taxonomy value
28+
- `appliesto: ✅ NoSQL` - Standard documentation badge
29+
30+
## Content formatting
31+
32+
Code blocks, queries, and documentation structure guidelines.
33+
34+
### Content completeness
35+
36+
- Ensure account creation steps reference the correct Azure portal experience
37+
38+
### Code blocks
39+
40+
Use the appropriate fenced code block with the corresponding language identifier for SDK samples. Supported languages:
41+
42+
- `csharp` - .NET SDK
43+
- `javascript` - Node.js SDK (JavaScript)
44+
- `typescript` - Node.js SDK (TypeScript)
45+
- `python` - Python SDK
46+
- `java` - Java SDK
47+
- `go` - Go SDK
48+
- `rust` - Rust SDK
49+
50+
Example pattern:
51+
52+
````markdown
53+
```csharp
54+
using Microsoft.Azure.Cosmos;
55+
CosmosClient client = new(endpoint, credential);
56+
```
57+
```
58+
59+
### Multi-language SDK samples
60+
61+
Use consecutive fenced code blocks with language identifiers for SDK samples. Supported languages:
62+
63+
Example pattern:
64+
65+
````markdown
66+
```csharp
67+
using Microsoft.Azure.Cosmos;
68+
CosmosClient client = new(endpoint, credential);
69+
```
70+
71+
```python
72+
from azure.cosmos import CosmosClient
73+
client = CosmosClient(endpoint, credential)
74+
```
75+
76+
```javascript
77+
const { CosmosClient } = require('@azure/cosmos');
78+
const client = new CosmosClient({ endpoint, aadCredentials: credential });
79+
```
80+
````
81+
82+
### NoSQL queries
83+
84+
- Use `nosql` for Azure Cosmos DB query language
85+
- Use `json` for query results or document examples
86+
87+
````markdown
88+
```nosql
89+
SELECT c.id, c.name FROM c WHERE c.status = "active"
90+
```
91+
92+
```json
93+
[
94+
{ "id": "1", "name": "Example" }
95+
]
96+
```
97+
````
98+
99+
### Azure CLI and infrastructure
100+
101+
- Use `azurecli` for Azure CLI commands
102+
- Use `json` for ARM/Bicep output
103+
- Use zone pivots (`zone_pivot_groups`) for portal/CLI/PowerShell/Bicep variations
104+
105+
## Technical review
106+
107+
Best practices to verify when reviewing content for technical accuracy.
108+
109+
### Data modeling
110+
111+
- Items must stay well under 2MB limit - flag content suggesting large documents or unbounded arrays
112+
- Embed related data retrieved together - flag N+1 query patterns (multiple lookups for related data)
113+
- Use type discriminators (`type` property) when storing multiple entity types in one container
114+
- Reference data when items grow large - use separate documents for unbounded relationships (comments on posts)
115+
- Version document schemas - include `schemaVersion` field for safe schema evolution
116+
117+
### Partition key design
118+
119+
- Plan for 20GB logical partition limit - flag partition keys that could accumulate unbounded data
120+
- Choose high-cardinality keys - flag low-cardinality keys like `status`, `region`, or boolean fields
121+
- Align partition key with query patterns - most frequent queries should be single-partition
122+
- Consider hierarchical partition keys for multi-tenant scenarios
123+
- Create synthetic partition keys when no single field works (combine fields)
124+
125+
Examples of problematic partition key choices:
126+
127+
| Problematic | Why | Better alternative |
128+
| --- | --- | --- |
129+
| `/status` | Only few values, creates hot partitions | `/customerId` or `/tenantId` |
130+
| `/createdDate` | All current writes hit same partition | `/userId` with time-bucketing |
131+
| `/region` | Uneven distribution, large geographic areas become hot | `/customerId` |
132+
133+
### Query optimization
134+
135+
- Include partition key in WHERE clause - flag cross-partition queries without justification
136+
- Project only needed fields - flag `SELECT *` in production code
137+
- Use parameterized queries - flag string concatenation in query building
138+
- Use continuation tokens for pagination - flag OFFSET/LIMIT for deep pagination
139+
- Order filters by selectivity - most selective filters first in WHERE clause
140+
141+
```csharp
142+
// Incorrect - vulnerable to injection, no query plan caching
143+
var query = $"SELECT * FROM c WHERE c.id = '{userId}'";
144+
145+
// Correct - parameterized
146+
var query = new QueryDefinition("SELECT c.id, c.name FROM c WHERE c.id = @id")
147+
.WithParameter("@id", userId);
148+
```
149+
150+
### SDK usage
151+
152+
- CosmosClient must be singleton - flag creating new clients per request
153+
- Use async APIs - flag `.Result` or `.Wait()` blocking calls
154+
- Use Direct connection mode for production - Gateway mode adds latency
155+
- Configure preferred regions for multi-region accounts
156+
- Log diagnostics for slow or failed operations
157+
- Handle 429 errors - verify retry configuration is documented
158+
159+
```csharp
160+
// Incorrect - creates connection per request
161+
public Order GetOrder(string id) {
162+
using var client = new CosmosClient(connectionString); // Wrong!
163+
// ...
164+
}
165+
166+
// Correct - singleton via DI
167+
public class OrderService {
168+
private readonly CosmosClient _client; // Injected singleton
169+
// ...
170+
}
171+
```
172+
### Connection and authentication
173+
174+
- Verify connection strings use the correct Azure Cosmos DB format
175+
- Ensure authentication examples show both connection string and Microsoft Entra ID options where applicable
176+
- Prioritize Microsoft Entra ID authentication in examples, as connection string auth is not preferred
177+
178+
### Security
179+
180+
- Disable public network access and use private endpoints exclusively for production deployments
181+
- Enable Network Security Perimeter (NSP) for additional network isolation boundaries
182+
- Use managed identities for Azure service-to-service authentication - avoid embedding credentials in code
183+
- Separate Azure identities for control plane (account management) and data plane (data operations)
184+
- Use Azure RBAC for control plane operations and native RBAC for data plane access
185+
- Enforce TLS 1.3 for transport security - use minimum TLS version configuration
186+
187+
### Indexing
188+
189+
- Exclude unused paths from indexing - reduces write RU cost by 20-80%
190+
- Add composite indexes for multi-property ORDER BY - prevents query failures
191+
- Verify indexing policy matches documented query patterns
192+
- Use spatial indexes for geospatial queries
193+
194+
### Throughput and scaling
195+
196+
- Use autoscale for variable workloads - scales between 10-100% of max RU/s
197+
- Consider serverless for dev/test environments - pay only for consumed RU
198+
- Understand burst capacity - unused RU accumulates for short spikes
199+
- Choose container vs database throughput based on isolation needs
200+
201+
### Global distribution
202+
203+
- Configure automatic failover for high availability
204+
- Choose appropriate consistency level - Session is default and recommended for most scenarios
205+
- Configure multi-region writes for globally distributed applications
206+
- Enable zone redundancy for single-region high availability (99.995% SLA)
207+
208+
| Consistency level | Use case |
209+
| --- | --- |
210+
| Strong | Financial transactions, inventory management |
211+
| Bounded staleness | Stock tickers, leaderboards |
212+
| Session (default) | User sessions, shopping carts |
213+
| Eventual | Analytics, non-critical reads |
214+
215+
### Change feed patterns
216+
217+
- Use change feed for materialized views - eliminates expensive cross-partition queries
218+
- Implement event-driven architectures with change feed processor
219+
- Use lease container to track processor progress
220+
221+
### Monitoring and diagnostics
222+
223+
- Track P99 latency, not just average - average hides tail latency issues affecting user experience
224+
- Monitor RU consumption per operation - enables cost optimization and capacity planning
225+
- Set up alerts for 429 throttling - indicates under-provisioned throughput
226+
- Enable diagnostic logging (DataPlaneRequests, QueryRuntimeStatistics, PartitionKeyStatistics)
227+
- Log SDK diagnostics for slow or failed operations - includes retry info, regions contacted, connection details
228+
- Monitor normalized RU consumption - alert if sustained above 90%
229+
230+
### Local development with emulator
231+
232+
- Use Gateway connection mode with emulator - Direct mode has SSL certificate issues
233+
- Import emulator SSL certificate for Java SDK - required for HTTPS connections
234+
- Use well-known emulator key: `C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==`
235+
- Override environment variables to avoid cloud connection conflicts - use `load_dotenv(override=True)` in Python or environment-specific config files
236+
237+
### SDK-specific requirements
238+
239+
Apply these checks only when reviewing articles with code samples in the corresponding language.
240+
241+
#### .NET SDK articles
242+
243+
When an article includes .NET/C# code samples using `Microsoft.Azure.Cosmos`:
244+
245+
- Verify the article includes a note about the explicit `Newtonsoft.Json` package dependency
246+
- The SDK requires this package (version 13.0.3+) but doesn't install it automatically
247+
- Flag .NET quickstarts or tutorials that don't include this prerequisite
248+
249+
Example note to include:
250+
251+
```markdown
252+
> [!IMPORTANT]
253+
> The `Microsoft.Azure.Cosmos` SDK requires an explicit reference to `Newtonsoft.Json` version 13.0.3 or higher. Add this package to your project using `dotnet add package Newtonsoft.Json`.
254+
```
255+
256+
#### Java SDK articles
257+
258+
When an article includes Java code samples using `com.azure:azure-cosmos`:
259+
260+
- Verify Spring Boot version compatibility is documented:
261+
- Spring Boot 3.x requires Java 17+
262+
- Spring Boot 2.7.x works with Java 8, 11, or 17
263+
- Flag Java quickstarts that don't mention Java version requirements
264+
- For emulator usage: document that Gateway mode is required (Direct mode has SSL issues)
265+
266+
| Spring Boot | Minimum Java | Recommended |
267+
| --- | --- | --- |
268+
| 3.2.x, 3.1.x, 3.0.x | Java 17 | Java 17 or 21 |
269+
| 2.7.x | Java 8 | Java 11 or 17 |

0 commit comments

Comments
 (0)