From 5c29f4be6cc220d1d1de62dd0a32d0ca289daadd Mon Sep 17 00:00:00 2001 From: Hal Spang Date: Thu, 13 Nov 2025 15:23:07 -0800 Subject: [PATCH 1/8] Introduce custom copilot review instructions Signed-off-by: Hal Spang --- .github/copilot-instructions.md | 69 +++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000..e064f7d9 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,69 @@ +# GitHub Copilot Instructions + +This repository contains both Python and C# code. +All python code resides under the `python/` directory. +All C# code resides under the `dotnet/` directory. + +The purpose of the code is to provide a framework for building AI agents. + +When contributing to this repository, please follow these guidelines: + +## C# Code Guidelines + +Here are some general guidelines that apply to all code. + +- The top of all *.cs files should have a copyright notice: `// Copyright (c) Microsoft. All rights reserved.` +- All public methods and classes should have XML documentation comments. +- No change should introduce a breaking change unless an exception is otherwise noted in the PR Summary, linked github issue, or discussion. + - Breaking change reference: https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/breaking-change-rules.md + +### C# Sample Code Guidelines + +Sample code is located in the `samples` directory. + +When adding a new sample, follow these steps: + +- The sample should be a standalone .net project in one of the subdirectories of the samples directory. +- The directory name should be the same as the project name. +- The directory should contain a README.md file that explains what the sample does and how to run it. +- The README.md file should follow the same format as other samples. +- The csproj file should match the directory name. +- The csproj file should be configured in the same way as other samples. +- The project should preferably contain a single Program.cs file that contains all the sample code. +- The sample should be added to the solution file in the samples directory. +- The sample should be tested to ensure it works as expected. +- A reference to the new samples should be added to the README.md file in the parent directory of the new sample. + +The sample code should follow these guidelines: + +- Configuration settings should be read from environment variables, e.g. `var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");`. +- Environment variables should use upper snake_case naming convention. +- Secrets should not be hardcoded in the code or committed to the repository. +- The code should be well-documented with comments explaining the purpose of each step. +- The code should be simple and to the point, avoiding unnecessary complexity. +- Prefer inline literals over constants for values that are not reused. For example, use `new ChatClientAgent(chatClient, instructions: "You are a helpful assistant.")` instead of defining a constant for "instructions". +- Ensure that all private classes are sealed +- Use the Async suffix on the name of all async methods that return a Task or ValueTask. +- Prefer defining variables using types rather than var, to help users understand the types involved. +- Follow the patterns in the samples in the same directories where new samples are being added. +- The structure of the sample should be as follows: + - The top of the Program.cs should have a copyright notice: `// Copyright (c) Microsoft. All rights reserved.` + - Then add a comment describing what the sample is demonstrating. + - Then add the necessary using statements. + - Then add the main code logic. + - Finally, add any helper methods or classes at the bottom of the file. + +### C# Unit Test Guidelines + +Unit tests are located in the `test` root directory in projects with a `.Tests.csproj` suffix. + +Unit tests should follow these guidelines: + +- Use `this.` for accessing class members +- Add Arrange, Act and Assert comments for each test +- Ensure that all private classes, that are not subclassed, are sealed +- Use the Async suffix on the name of all async methods +- Use the Moq library for mocking objects where possible +- Validate that each test actually tests the target behavior, e.g. we should not have tests that creates a mock, calls the mock and then verifies that the mock was called, without the target code being involved. We also shouldn't have tests that test language features, e.g. something that the compiler would catch anyway. +- Avoid adding excessive comments to tests. Instead favour clear easy to understand code. +- Follow the patterns in the unit tests in the same project or classes to which new tests are being added \ No newline at end of file From 15c37632ee23c3ef242c07822ec4ee412431377c Mon Sep 17 00:00:00 2001 From: Hal Spang Date: Thu, 13 Nov 2025 15:31:39 -0800 Subject: [PATCH 2/8] Grammatical fixes Signed-off-by: Hal Spang --- .github/copilot-instructions.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index e064f7d9..dea1d102 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,10 +1,8 @@ # GitHub Copilot Instructions -This repository contains both Python and C# code. -All python code resides under the `python/` directory. -All C# code resides under the `dotnet/` directory. +This repository contains C# code. -The purpose of the code is to provide a framework for building AI agents. +The purpose of the code is to provide a standalone SDK for interacting with Durable Functions. When contributing to this repository, please follow these guidelines: @@ -15,7 +13,9 @@ Here are some general guidelines that apply to all code. - The top of all *.cs files should have a copyright notice: `// Copyright (c) Microsoft. All rights reserved.` - All public methods and classes should have XML documentation comments. - No change should introduce a breaking change unless an exception is otherwise noted in the PR Summary, linked github issue, or discussion. - - Breaking change reference: https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/breaking-change-rules.md + - Breaking change reference: https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/breaking-change-rules.md +- Use `this.` for accessing class members. +- Use the Async suffix on the name of all async methods. ### C# Sample Code Guidelines @@ -23,7 +23,7 @@ Sample code is located in the `samples` directory. When adding a new sample, follow these steps: -- The sample should be a standalone .net project in one of the subdirectories of the samples directory. +- The sample should be a standalone .NET project in one of the subdirectories of the samples directory. - The directory name should be the same as the project name. - The directory should contain a README.md file that explains what the sample does and how to run it. - The README.md file should follow the same format as other samples. @@ -59,11 +59,11 @@ Unit tests are located in the `test` root directory in projects with a `.Tests.c Unit tests should follow these guidelines: -- Use `this.` for accessing class members -- Add Arrange, Act and Assert comments for each test -- Ensure that all private classes, that are not subclassed, are sealed -- Use the Async suffix on the name of all async methods -- Use the Moq library for mocking objects where possible +- Use `this.` for accessing class members. +- Add Arrange, Act and Assert comments for each test. +- Ensure that all private classes, that are not subclassed, are sealed. +- Use the Async suffix on the name of all async methods. +- Use the Moq library for mocking objects where possible. - Validate that each test actually tests the target behavior, e.g. we should not have tests that creates a mock, calls the mock and then verifies that the mock was called, without the target code being involved. We also shouldn't have tests that test language features, e.g. something that the compiler would catch anyway. - Avoid adding excessive comments to tests. Instead favour clear easy to understand code. -- Follow the patterns in the unit tests in the same project or classes to which new tests are being added \ No newline at end of file +- Follow the patterns in the unit tests in the same project or classes to which new tests are being added. \ No newline at end of file From d274d060e3dad7eccaccae65eda9818cf5da67fd Mon Sep 17 00:00:00 2001 From: Hal Spang Date: Thu, 13 Nov 2025 15:44:46 -0800 Subject: [PATCH 3/8] Align async and sealed class recommendations Signed-off-by: Hal Spang --- .github/copilot-instructions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index dea1d102..e6e46da4 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -42,8 +42,8 @@ The sample code should follow these guidelines: - The code should be well-documented with comments explaining the purpose of each step. - The code should be simple and to the point, avoiding unnecessary complexity. - Prefer inline literals over constants for values that are not reused. For example, use `new ChatClientAgent(chatClient, instructions: "You are a helpful assistant.")` instead of defining a constant for "instructions". -- Ensure that all private classes are sealed -- Use the Async suffix on the name of all async methods that return a Task or ValueTask. +- Ensure that all private classes, that are not subclassed, are sealed. +- Use the Async suffix on the name of all async methods. - Prefer defining variables using types rather than var, to help users understand the types involved. - Follow the patterns in the samples in the same directories where new samples are being added. - The structure of the sample should be as follows: From 1b4361a09375b0807160c0df7a9cb17de65f88b7 Mon Sep 17 00:00:00 2001 From: Hal Spang Date: Thu, 13 Nov 2025 15:52:35 -0800 Subject: [PATCH 4/8] Fix the copyright notice Signed-off-by: Hal Spang --- .github/copilot-instructions.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index e6e46da4..80493469 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -10,7 +10,11 @@ When contributing to this repository, please follow these guidelines: Here are some general guidelines that apply to all code. -- The top of all *.cs files should have a copyright notice: `// Copyright (c) Microsoft. All rights reserved.` +- The top of all *.cs files should have a copyright notice: + ```csharp + // Copyright (c) Microsoft Corporation. + // Licensed under the MIT License. + ``` - All public methods and classes should have XML documentation comments. - No change should introduce a breaking change unless an exception is otherwise noted in the PR Summary, linked github issue, or discussion. - Breaking change reference: https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/breaking-change-rules.md @@ -47,7 +51,11 @@ The sample code should follow these guidelines: - Prefer defining variables using types rather than var, to help users understand the types involved. - Follow the patterns in the samples in the same directories where new samples are being added. - The structure of the sample should be as follows: - - The top of the Program.cs should have a copyright notice: `// Copyright (c) Microsoft. All rights reserved.` + - The top of the Program.cs should have a copyright notice: + ```csharp + // Copyright (c) Microsoft Corporation. + // Licensed under the MIT License. + ``` - Then add a comment describing what the sample is demonstrating. - Then add the necessary using statements. - Then add the main code logic. @@ -65,5 +73,5 @@ Unit tests should follow these guidelines: - Use the Async suffix on the name of all async methods. - Use the Moq library for mocking objects where possible. - Validate that each test actually tests the target behavior, e.g. we should not have tests that creates a mock, calls the mock and then verifies that the mock was called, without the target code being involved. We also shouldn't have tests that test language features, e.g. something that the compiler would catch anyway. -- Avoid adding excessive comments to tests. Instead favour clear easy to understand code. +- Avoid adding excessive comments to tests. Instead favor clear easy to understand code. - Follow the patterns in the unit tests in the same project or classes to which new tests are being added. \ No newline at end of file From dc8b787a97f199a3bb0bf8c4c243e363efa71639 Mon Sep 17 00:00:00 2001 From: Hal Spang Date: Thu, 13 Nov 2025 15:56:21 -0800 Subject: [PATCH 5/8] More grammar fixes Signed-off-by: Hal Spang --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 80493469..f9b52632 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -72,6 +72,6 @@ Unit tests should follow these guidelines: - Ensure that all private classes, that are not subclassed, are sealed. - Use the Async suffix on the name of all async methods. - Use the Moq library for mocking objects where possible. -- Validate that each test actually tests the target behavior, e.g. we should not have tests that creates a mock, calls the mock and then verifies that the mock was called, without the target code being involved. We also shouldn't have tests that test language features, e.g. something that the compiler would catch anyway. +- Validate that each test actually tests the target behavior, e.g. we should not have tests that create a mock, call the mock and then verify that the mock was called, without the target code being involved. We also shouldn't have tests that test language features, e.g. something that the compiler would catch anyway. - Avoid adding excessive comments to tests. Instead favor clear easy to understand code. - Follow the patterns in the unit tests in the same project or classes to which new tests are being added. \ No newline at end of file From f57c4bd49ffcdc2092dddea6f89e0e3a00312c72 Mon Sep 17 00:00:00 2001 From: Hal Spang Date: Thu, 13 Nov 2025 16:04:05 -0800 Subject: [PATCH 6/8] Move some guidelines to base C# section Signed-off-by: Hal Spang --- .github/copilot-instructions.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index f9b52632..20e3e34d 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -20,6 +20,7 @@ Here are some general guidelines that apply to all code. - Breaking change reference: https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/breaking-change-rules.md - Use `this.` for accessing class members. - Use the Async suffix on the name of all async methods. +- Ensure that all private classes, that do not serve as base classes, are sealed. ### C# Sample Code Guidelines @@ -45,8 +46,7 @@ The sample code should follow these guidelines: - Secrets should not be hardcoded in the code or committed to the repository. - The code should be well-documented with comments explaining the purpose of each step. - The code should be simple and to the point, avoiding unnecessary complexity. -- Prefer inline literals over constants for values that are not reused. For example, use `new ChatClientAgent(chatClient, instructions: "You are a helpful assistant.")` instead of defining a constant for "instructions". -- Ensure that all private classes, that are not subclassed, are sealed. +- Prefer inline literals over constants for values that are not reused. For example, use `new ChatClientAgent(chatClient, instructions: "You are a helpful assistant.")` instead of defining a constant for "instructions - Use the Async suffix on the name of all async methods. - Prefer defining variables using types rather than var, to help users understand the types involved. - Follow the patterns in the samples in the same directories where new samples are being added. @@ -67,9 +67,7 @@ Unit tests are located in the `test` root directory in projects with a `.Tests.c Unit tests should follow these guidelines: -- Use `this.` for accessing class members. -- Add Arrange, Act and Assert comments for each test. -- Ensure that all private classes, that are not subclassed, are sealed. +- Add Arrange, Act and Assert comments for each test - Use the Async suffix on the name of all async methods. - Use the Moq library for mocking objects where possible. - Validate that each test actually tests the target behavior, e.g. we should not have tests that create a mock, call the mock and then verify that the mock was called, without the target code being involved. We also shouldn't have tests that test language features, e.g. something that the compiler would catch anyway. From 48ada0eff96915306652f35cf5b9c74ec4a159e6 Mon Sep 17 00:00:00 2001 From: Hal Spang Date: Thu, 13 Nov 2025 16:08:44 -0800 Subject: [PATCH 7/8] The grammar train continues Signed-off-by: Hal Spang --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 20e3e34d..a4ab7a6c 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -37,7 +37,7 @@ When adding a new sample, follow these steps: - The project should preferably contain a single Program.cs file that contains all the sample code. - The sample should be added to the solution file in the samples directory. - The sample should be tested to ensure it works as expected. -- A reference to the new samples should be added to the README.md file in the parent directory of the new sample. +- A reference to the new sample should be added to the README.md file in the parent directory of the new sample. The sample code should follow these guidelines: From ae66a0d11c099030e82e6260e6237d1bf58ba7a8 Mon Sep 17 00:00:00 2001 From: Hal Spang Date: Fri, 14 Nov 2025 11:44:15 -0800 Subject: [PATCH 8/8] Update purpose and clarify requirements Signed-off-by: Hal Spang --- .github/copilot-instructions.md | 15 ++++----------- 1 file changed, 4 insertions(+), 11 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index a4ab7a6c..31621df5 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -2,7 +2,7 @@ This repository contains C# code. -The purpose of the code is to provide a standalone SDK for interacting with Durable Functions. +The purpose of this code is to provide a standalone SDK that can be used to interact with the Durable Task coding paradigm, both through Azure Functions (Durable Functions) and non-function based Durable Task Scheduler (DTS). When contributing to this repository, please follow these guidelines: @@ -46,17 +46,11 @@ The sample code should follow these guidelines: - Secrets should not be hardcoded in the code or committed to the repository. - The code should be well-documented with comments explaining the purpose of each step. - The code should be simple and to the point, avoiding unnecessary complexity. -- Prefer inline literals over constants for values that are not reused. For example, use `new ChatClientAgent(chatClient, instructions: "You are a helpful assistant.")` instead of defining a constant for "instructions -- Use the Async suffix on the name of all async methods. +- Prefer inline literals over constants for values that are not reused. For example, use `new ChatClientAgent(chatClient, instructions: "You are a helpful assistant.")` instead of defining a constant for "instructions". - Prefer defining variables using types rather than var, to help users understand the types involved. - Follow the patterns in the samples in the same directories where new samples are being added. - The structure of the sample should be as follows: - - The top of the Program.cs should have a copyright notice: - ```csharp - // Copyright (c) Microsoft Corporation. - // Licensed under the MIT License. - ``` - - Then add a comment describing what the sample is demonstrating. + - Add a comment describing what the sample is demonstrating. - Then add the necessary using statements. - Then add the main code logic. - Finally, add any helper methods or classes at the bottom of the file. @@ -67,8 +61,7 @@ Unit tests are located in the `test` root directory in projects with a `.Tests.c Unit tests should follow these guidelines: -- Add Arrange, Act and Assert comments for each test -- Use the Async suffix on the name of all async methods. +- Add Arrange, Act and Assert comments for each - Use the Moq library for mocking objects where possible. - Validate that each test actually tests the target behavior, e.g. we should not have tests that create a mock, call the mock and then verify that the mock was called, without the target code being involved. We also shouldn't have tests that test language features, e.g. something that the compiler would catch anyway. - Avoid adding excessive comments to tests. Instead favor clear easy to understand code.