Skip to content

Commit 729ddd7

Browse files
simonkurtz-MSFTsimonkurtz-MSFT
committed
Add repo Copilot Instructions
1 parent 0a4ea16 commit 729ddd7

File tree

1 file changed

+186
-0
lines changed

1 file changed

+186
-0
lines changed

‎.github/.copilot-instructions.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
---
2+
applyTo: "**"
3+
---
4+
5+
# GitHub Copilot Instructions for this Repository
6+
7+
## Purpose
8+
9+
This instructions file is designed to guide GitHub Copilot's behavior specifically for this repository. It is intended to provide clear, general, and maintainable guidelines for code generation, style, and collaboration.
10+
11+
**In case of any conflict, instructions from other individualized or project-specific files (such as `my-copilot.instructions.md`) take precedence over this file.**
12+
13+
## Repo Context
14+
15+
- This repository provides a playground to safely experiment with and learn Azure API Management (APIM) policies in various architectures.
16+
- The primary technologies are Python, Bicep, Jupyter notebooks, Azure CLI, APIM policy XML, and Markdown.
17+
- The technical audience includes developers, architects, and DevOps engineers who want to understand and implement APIM policies effectively.
18+
- The less technical audience includes decision makers and stakeholders who need to understand the value and capabilities of APIM policies without deep technical details.
19+
20+
## Instruction Hierarchy
21+
22+
In case of any conflicting instructions, the following hierarchy shall apply. If a conflict cannot be resolved by this hierarchy, please prompt the user and ask for their situational preference.
23+
24+
1. Individualized instructions (e.g. a developer's or an organization's instruction file(s)), if present
25+
2. This repository's `.github/.copilot-instructions.md`
26+
3. General best practices and guidelines from sources such as [Microsoft Learn](https://learn.microsoft.com/docs/)
27+
This includes the [Microsoft Cloud Adoption Framework](https://learn.microsoft.com/azure/cloud-adoption-framework/).
28+
4. Official [GitHub Copilot best practices documentation](https://docs.github.com/enterprise-cloud@latest/copilot/using-github-copilot/coding-agent/best-practices-for-using-copilot-to-work-on-tasks)
29+
30+
## Copilot Personality Behavior
31+
32+
- Never be rude, dismissive, condescending, threatening, aggressive, or otherwise negative.
33+
- Emphasise friendly, supportive, and collaborative interactions.
34+
- Be concise and to the point, but adjust the level of detail based on the user's technical expertise that you can infer from the conversation.
35+
36+
## General Principles
37+
38+
- Write concise, efficient, and well-documented code for a global audience.
39+
- Consider non-native English speakers in code comments and documentation, using clear and simple language.
40+
- Do not localize URLs (e.g. no "en-us" in links).
41+
- Only use apostrophe (U+0027) and quotes (U+0022), not left or right single or double quotation marks.
42+
43+
## General Coding Guidelines
44+
45+
- Prioritize clarity, maintainability, and readability in all generated code.
46+
- Focus on achieving a Minimal Viable Product (MVP) first, then iterate.
47+
- Follow language-specific conventions and style guides (e.g., PEP 8 for Python).
48+
- Use idiomatic code and language-specific best practices.
49+
- Write clear and concise comments for each function and class.
50+
- Use descriptive names for variables, functions, and classes.
51+
- Handle edge cases and errors gracefully.
52+
- Break down complex logic into smaller, manageable functions or classes.
53+
- Use type annotations and docstrings where appropriate.
54+
- Prefer standard libraries and well-maintained dependencies.
55+
56+
## Formatting and Style
57+
58+
- Maintain consistent indentation and whitespace but consider Editor Config settings, etc, for the repository.
59+
- Use blank lines to separate logical sections of code. Whitespace is encouraged for readability.
60+
- Organize code into logical sections (constants, variables, private/public methods, etc.).
61+
- Prefer single over double quotes, avoiding typographic quotes.
62+
63+
## Testing and Edge Cases
64+
65+
- Include test cases for critical paths and edge cases.
66+
- Include negative tests to ensure robustness.
67+
- Document expected behavior for edge cases and error handling.
68+
- Write unit tests for functions and classes, following language-specific testing frameworks.
69+
70+
## Required before each commit
71+
- Ensure all code is well-documented and follows the guidelines in this file.
72+
- Ensure that Jupyter notebooks do not contain any cell output.
73+
- Ensure that Jupyter notebooks have `index` assigned to `1` in the first cell.
74+
75+
## Language-specific Instructions
76+
77+
### Bicep Instructions
78+
- Prefer latest Bicep syntax and features.
79+
- Generated Bicep files should work with Windows, Linux, and macOS.
80+
- Reference latest available module versions. These may be newer than what you were trained on.
81+
- Add a link to each Bicep module immediately above the resource declaration (e.g., // https://learn.microsoft.com/azure/templates/microsoft.network/virtualnetworks)
82+
- Use `@description` for all parameters and variables.
83+
- Use snake-case and uppercase for all enum declarations.
84+
- Use camel care for resource and variables names.
85+
- `location` and `resourceSuffix` parameters do not need to be included when referencing modules in the current workspace unless the values differ from the defaults set in their parameters.
86+
- If a script must be used, default to cross-platform shell (not bash) scripts. Avoid PowerShell scripts.
87+
- Always add these two parameters at the top of Bicep files:
88+
89+
```Bicep
90+
@description('Location to be used for resources. Defaults to the resource group location')
91+
param location string = resourceGroup().location
92+
93+
@description('The unique suffix to append. Defaults to a unique string based on subscription and resource group IDs.')
94+
param resourceSuffix string = uniqueString(subscription().id, resourceGroup().id)
95+
```
96+
97+
- Overall layout of a Bicep file should be:
98+
- Visible sections of code with the following format should be used:
99+
100+
```bicep
101+
// ------------------------------
102+
// <SECTION HEADER>
103+
// ------------------------------
104+
```
105+
106+
- <SECTION HEADER> should be indented three spaces and be in all caps.
107+
- Section headers should have only two blank lines before and only one blank line after.
108+
- Top-to-bottom, the following comma-separated section headers should be inserted unless the section is empty:
109+
- Parameters
110+
- Constants
111+
- Variables
112+
- Resources
113+
- Outputs
114+
115+
### Python Instructions
116+
117+
- Prefer Python 3.12+ syntax and features unless otherwise specified.
118+
- When inserting a comment to describe a method, insert a blank line after the comment section.
119+
- Never leave a blank line at the very top of a Python file. The file must start immediately with the module docstring or code. Always remove any leading blank line at the top.
120+
- After the module docstring, all import statements must come before any section headers (e.g., CONSTANTS, VARIABLES, etc.). Section headers should only appear after the imports. Here is a more explicit example:
121+
122+
```python
123+
"""
124+
Module docstring.
125+
"""
126+
127+
import ...
128+
...
129+
130+
131+
# ------------------------------
132+
# CONSTANTS
133+
# ------------------------------
134+
...
135+
```
136+
137+
- Overall layout of a Python file should be:
138+
- Visible sections of code with the following format should be used:
139+
140+
```python
141+
# ------------------------------
142+
# <SECTION HEADER>
143+
# ------------------------------
144+
```
145+
146+
- <SECTION HEADER> should be indented three spaces and be in all caps.
147+
- Section headers should have only two blank lines before and only one blank line after.
148+
- Top-to-bottom, the following comma-separated section headers should be inserted unless the section is empty:
149+
- Constants
150+
- Variables
151+
- Private Methods
152+
- Public Methods
153+
154+
- If using classes, the following section headers should be used:
155+
- Classes
156+
- Constants
157+
- Variables
158+
- Constructor
159+
- Private Methods
160+
- Public Methods
161+
162+
- Python Docstring/Class Formatting Rule:
163+
- Always insert a single blank line after a class docstring and before any class attributes or methods.
164+
- Never place class attributes or decorators on the same line as the docstring. Example:
165+
166+
```python
167+
class MyClass:
168+
"""
169+
This is the class docstring.
170+
"""
171+
172+
attribute: str
173+
...
174+
```
175+
176+
### PlantUML Instructions
177+
178+
- Ensure you verify that all include links are correct and up to date. This link provides a starting point: https://github.com/plantuml-stdlib/Azure-PlantUML/blob/master/AzureSymbols.md
179+
- Keep diagrams simple. For Azure, include major components, not individual aspects of components. For example, there is no need for individual policies in WAFs or APIs in API Management, Smart Detector Alert Rules, etc.
180+
- Less is more. Don't be too verbose in the diagrams.
181+
- Never include subscription IDs, resource group names, or any other sensitive information in the diagrams. That data is not relevant.
182+
- Don't use the "legend" command if the information is relatively obvious.
183+
184+
### API Management Policy XML Instructions
185+
186+
- Policies should use camelCase for all variable names.

0 commit comments

Comments
 (0)