Add copilot-instructions.md to get GitHub Copilot up to speed with the toolkit's coding standards and preferences

[GeorgeLeithead]

With the recent release of GitHub Copilot Free, an increasing number of community members are leveraging this tool to assist with their contributions to the .NET MAUI Community Toolkit. To ensure that contributions align with the toolkit's coding standards and preferences, we propose the addition of a copilot-instructions.md file to the repository.

Objective
The primary objective of this proposal is to guide GitHub Copilot in adhering to the .NET MAUI Community Toolkit's coding standards and preferences. By providing clear instructions, we can enhance the quality and consistency of contributions made by the community.

Benefits

• Enhanced Code Quality: By defining coding standards and preferences, we can ensure that all contributions meet the toolkit's quality requirements.
• Consistency: A standardized approach to coding will result in a more uniform codebase, making it easier to maintain and extend.
  Efficiency: Contributors can quickly get up to speed with the toolkit's guidelines, reducing the time spent on code reviews and revisions.
• Context-Aware Responses: GitHub Copilot will use the copilot-instructions.md file to provide context-aware responses, improving the relevance and accuracy of its suggestions.

Implementation

• Create copilot-instructions.md: This file will contain detailed information on the toolkit's coding standards and preferences, including:
  • Code formatting guidelines
  • Naming conventions
  • Best practices for writing maintainable and efficient code
  • Common pitfalls to avoid
• Integrate with GitHub Copilot: Utilize GitHub Copilot's Custom Instructions feature to ensure that it references the copilot-instructions.md file when generating code suggestions and answering questions.
• Continuous Updates: Regularly update the copilot-instructions.md file to reflect any changes in the toolkit's standards and preferences.

Conclusion
Adding a copilot-instructions.md file to the .NET MAUI Community Toolkit repository will significantly benefit the community by providing clear guidance on coding standards and preferences. This will not only improve the quality and consistency of contributions but also streamline the development process by leveraging GitHub Copilot's capabilities.

An example could be as follows (which I have collated by taking the CONTRIBUTING.md and expanding upon).

# Overview
This document provides guidelines for using GitHub Copilot to contribute to the .NET MAUI Community Toolkit. It includes instructions on setting up your environment, writing code, and following best practices specific to .NET MAUI.

## Prerequisites
1.	Install the latest stable (.NET SDK)[https://dotnet.microsoft.com/en-us/download].
2.	Install .NET MAUI workloads (we recommend using Visual Studio installer).

## Setting Up GitHub Copilot
1.	Ensure you have GitHub Copilot installed and enabled in Visual Studio.
2.	Familiarize yourself with the basic usage of GitHub Copilot by reviewing the (official documentation)[https://docs.github.com/en/copilot].

## Writing Code with GitHub Copilot
### General Guidelines
* Use GitHub Copilot to assist with code completion, documentation, and generating boilerplate code.
* Always review and test the code suggested by GitHub Copilot to ensure it meets the project's standards and requirements.

### Specific to .NET MAUI
* Ensure that any UI components or controls are compatible with .NET MAUI.
* Avoid using Xamarin.Forms-specific code unless there is a direct .NET MAUI equivalent.
* Follow the project's coding style and best practices as outlined in the (contributing)[https://github.com/CommunityToolkit/Maui/blob/main/CONTRIBUTING.md] document.

## Best Practices
* Use **Trace.WriteLine()** for debug logging instead of **Debug.WriteLine()**.
* Include a **CancellationToken** as a parameter for methods returning **Task** or **ValueTask**.
* Use **is** for null checking and type checking.
* Use file-scoped namespaces to reduce code verbosity.
* Avoid using the **!** null forgiving operator.
** Follow naming conventions for enums and property names.

### Debug Logging
* Always use `Trace.WriteLine()` instead of `Debug.WriteLine` for debug logging because `Debug.WriteLine` is removed by the compiler in Release builds

### Methods Returning Task and ValueTask
* Always include a `CancellationToken` as a parameter to every method returning `Task` or `ValueTask`
* If the method is public, provide a the default value for the `CancellationToken` (e.g. `CancellationToken token = default`)
  * If the method is not public, do not provide a default value for the `CancellationToken`
* Use `CancellationToken.ThrowIfCancellationRequested()` to verify the `CancellationToken`

### Enums
* Always use `Unknown` at index 0 for return types that may have a value that is not known
* Always use `Default` at index 0 for option types that can use the system default option
* Follow naming guidelines for tense... `SensorSpeed` not `SensorSpeeds`
* Assign values (0,1,2,3) for all enums

### Property Names
* Include units only if one of the platforms includes it in their implementation. For instance HeadingMagneticNorth implies degrees on all platforms, but PressureInHectopascals is needed since platforms don't provide a consistent API for this.

### Units
* Use the standard units and most well accepted units when possible. For instance Hectopascals are used on UWP/Android and iOS uses Kilopascals so we have chosen Hectopascals.

### Pattern matching
#### Null checking
* Prefer using `is` when checking for null instead of `==`.

e.g.

```csharp
// null
if (something is null)
{

}

// or not null
if (something is not null)
{
   
}

• Avoid using the ! null forgiving operator to avoid the unintended introduction of bugs.

Type checking

• Prefer is when checking for types instead of casting.

e.g.

if (something is Bucket bucket)
{
   bucket.Empty();
}

File Scoped Namespaces

• Use file scoped namespaces to help reduce code verbosity.

e.g.

namespace CommunityToolkit.Maui.Converters;

using System;

class BoolToObjectConverter
{
}

Braces

Please use { } after if, for, foreach, do, while, etc.

e.g.

if (something is not null)
{
   ActOnIt();
}

NotImplementedException

• Please avoid adding new code that throws a NotImplementedException. According to the Microsoft Docs, we should only "throw a NotImplementedException exception in properties or methods in your own types when that member is still in development and will only later be implemented in production code. In other words, a NotImplementedException exception should be synonymous with 'still in development.'"
  In other words, NotImplementedException implies that a feature is still in development, indicating that the Pull Request is incomplete.

Bug Fixes

If you're looking for something to fix, please browse open issues.

Follow the style used by the .NET Foundation, with two primary exceptions:

• We do not use the private keyword as it is the default accessibility level in C#.
• We will not use _ or s_ as a prefix for internal or private field names
• We will use camelCaseFieldName for naming internal or private fields in both instance and static implementations

Read and follow our Pull Request template

Submitting Contributions

1. Fork the repository and create a new branch for your changes.
2. Implement your changes using GitHub Copilot as needed.
3. Ensure your changes include tests, samples, and documentation.
4. Open a pull request and follow the Pull Request template.

Additional Resources

• (GitHub Copilot Documentation)[https://docs.github.com/en/copilot]
• (.NET MAUI Documentation)[https://learn.microsoft.com/en-us/dotnet/maui/]

By following these guidelines, you can effectively use GitHub Copilot to contribute to the .NET MAUI Community Toolkit. Thank you for your contributions!

[GeorgeLeithead]

An example of the file can be found in this fork: https://github.com/GeorgeLeithead/CommunityToolkitMaui/tree/CoPilotInstructions

[ne0rrmatrix]

This is a great idea. I would love to see this in the toolkit.

[TheCodeTraveler]

Super cool! I didn’t know this existed!

Reading the docs, it looks like only someone with maintainer-access to the repo can add it as it requires access to the repo’s settings. I’ll take a look today to see about adding it 🙌

[TheCodeTraveler]

Ah - dang. We can't implement this because the CommunityToolkit GitHub Org doesn't have a Co-pilot subscription. I've reached out to the .NET Foundation to ask if they will be providing us a subscription and they do not currently have plans to do so 🤷‍♂️

So for now, we're blocked until something changes between in the .NET Foundation policy. Bummer!

I've added the blocked label to this discussion for now.

[GeorgeLeithead]

Do we really need a CoPilot subscription? From what I understand, this works with the end developers co-pilot, and it is therefore up to them to either not have/use co-pilot, and therefore nothing "should" change OR use the FREE/Paid license, and this will then direct the local instance to apply the rules.

[GeorgeLeithead]

Obviously if we want a code review at PUSH time, this is different, but my main goal was to help the 'entry level' developers, especially with boilerplate and to help guide them when they use CoPilot.

[ne0rrmatrix]

Has anyone checked out this branch and tested the difference in behaviour of copilot in visual studio or vscode? If it just works already in either of those I would add it as that is enough for end users to get real benefits from it? Just a thought? Compare and contrast results from main. It should be obvious if it is working right?