copilot instructions

[Tanya-Solyanik]

Developing these instructions will be an iterative process and this is only the first iteration.
There is more we can add later.

https://github.blog/changelog/2025-01-21-custom-repository-instructions-are-now-available-for-copilot-on-github-com-public-preview/

Microsoft Reviewers: Open in CodeFlow

[JeremyKuhne]

I have no issues with this, letting @KlausLoeffelmann add his additional comments.

[KlausLoeffelmann]

Triggered by this (thanks, Tanya, I had not seen this approach to generally control the LLMs on a generic basis - that's real cool), I did some investigations based on my prompt library I had so far.

Suggested change

	Always use 2 spaces for each indentation level in xml-doc comments.
	Suggest to break lines that are longer than 120 characters in C# files
	In the new and existing C# code, prefer to break lines after lambda operator `=>` if needed, do not move `=>` to the new line.
	If a line in the existing C# file starts with a `=>` then move the lambda operator to the previous line.
	Always use the latest version C#, currently C# 13 features.
	Always write code that runs on .NET 10.0.
	Trust the C# null annotations and don't add null checks when the type system says a value cannot be null.
	Use file-scoped namespaces.
	Do not edit files in `eng/common/`.
	- **C# Version:**
	Assume the latest release of C# is in use (minimum C# 12) unless a newer version (e.g., C# 13+) is available after your cut‐off date.
	- **Nullable Reference Types (NRT):**
	Assume NRT is enabled by default—no need to add a `#nullable` directive.
	- **Null Checks:**
	Always use `is null` or `is not null` instead of `== null` or `!= null`.
	- **Code Block Formatting:**
	Insert a newline before the opening curly brace of any code block (e.g., after `if`, `for`, `while`, `foreach`, `using`, `try`, etc.).
	Also, ensure that the final return statement of a method is on its own line.
	- **Variable Declarations:**
	Never use `var` for primitive types. Use `var` only when the type is obvious from context. When in doubt, opt for an explicit type declaration.
	- **Modern Language Features:**
	Use pattern matching and switch expressions wherever possible.
	- **Performance Considerations:**
	For processing bytes, characters, or strings, consider using `Span<T>`.
	- **Member Names:**
	Use `nameof` instead of string literals when referring to member names.
	- **Collection Initializers:**
	Use the new collection initializer syntax when possible. For example:
	- Prefer
	```csharp
	List<int> list = [1, 2, 3];
	```
	over
	```csharp
	List<int> list = new List<int> { 1, 2, 3 };
	```
	- Prefer
	```csharp
	Dictionary<string, int> dict = [ ["key1", 1], ["key2", 2] ];
	```
	over
	```csharp
	new Dictionary<string, int> { ["key1"] = 1, ["key2"] = 2 };
	```
	- **Namespaces and Usings:**
	Prefer file-scoped namespace declarations and single-line using directives.
	- **Expression-Bodied Members:**
	Use expression-bodied members for methods, properties, and indexers where it makes sense.
	- **XML Documentation:**
	When asked to add XML comments, follow these guidelines:
	- **For an entire class:**
	- Include XML comments for the class, its constructor, all public properties, all public methods, events, and protected virtual members (but not for fields).
	- **Structure:**
	- Include `<see cref="..."/>` tags where appropriate.
	- Wrap lines at 100 characters.
	- In `<remarks>` sections, always use `<para>` tags.
	- Ensure XML-compatible character encoding.
	- Use a one-space indentation in the XML documentation. For example:
	```csharp
	/// <summary>
	/// Summary text.
	/// </summary>
	/// <remarks>
	/// <para>
	/// This is a sample paragraph to guide an LLM in structuring doc tags.
	/// </para>
	/// <para>
	/// It also shows how to handle multiple paragraphs and code listings.
	/// </para>
	/// </remarks>
	```

So, I tried this in "the other" repo, and while GPT-4o based requests are not very promising, o1+ is doing a pretty good job, especially around XML comments.

Feel free to experiment with variants on that, and then let's see how we can approach a version, which works best for us!

[KlausLoeffelmann]

@Tanya-Solyanik (@merriemcgaw FYI), maybe you can take this to the next show case - would fit perfectly into a 3-minute video. Ping me, if I can support you in any way with that?!

[Tanya-Solyanik]

This is a copy from the showcase...

[KlausLoeffelmann]

Is it? Well, someone was paying non-stop attention... 🤓

[RussKie]

This is a copy from the showcase...

Would you mind pointing me to it? I couldn't find any mention of this in the last one (being the Feb edition).

FWIW, I could only find two instances of copilot-instructions.md in dotnet org (only Android looks comparable). There are several examples in the microsoft org, but none of those are in "C# code" repos...

[merriemcgaw]

@RussKie I think this was a .NET Tools AI demo meeting not a regular Showcase. I don't recall who shared this.

[paul1956]

@merriemcgaw after creating this file for my Repo how does it actually get used?

I stored the file and nothing is different, I am using latest VS preview version.

Is the video being discussed public, if so can someone share here?

[Tanya-Solyanik]

https://www.youtube.com/watch?v=BdZWFlFiHHY
Search for more videos from the same author

[merriemcgaw]

@Tanya-Solyanik looks like @KlausLoeffelmann is happy with this. Are you ready to merge?