You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .github/copilot-instructions.md
+64-18Lines changed: 64 additions & 18 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,21 +3,8 @@
3
3
## High level guidance
4
4
5
5
* Review the `CONTRIBUTING.md` file for instructions to build and test the software.
6
-
* Set the `NBGV_GitEngine` environment variable to `Disabled` before running any `dotnet` or `msbuild` commands.
7
-
8
-
## Environment Setup and Shallow Clone Workaround
9
-
10
-
This repository uses Nerdbank.GitVersioning which depends on git history for version calculation. Since GitHub Copilot Coding Agent operates on shallow clones, you MUST set the following environment variable before running any build commands:
11
-
12
-
```bash
13
-
export NBGV_GitEngine=Disabled
14
-
```
15
-
16
-
**Important**: The environment variable name and value are case-sensitive. This setting:
17
-
- Removes access to git history during builds
18
-
- Allows builds to succeed in shallow clone environments
19
-
- Results in incorrect version stamps (expected in Copilot environment)
20
-
- Still generates the `ThisAssembly` class but with fewer properties
6
+
* Run the `.github/Prime-ForCopilot.ps1` script (once) before running any `dotnet` or `msbuild` commands.
7
+
If you see any build errors about not finding git objects or a shallow clone, it may be time to run this script again.
* There should generally be one test project (under the `test` directory) per shipping project (under the `src` directory). Test projects are named after the project being tested with a `.Test` suffix.
48
-
* Tests should use the Xunit testing framework.
49
-
* Some tests are known to be unstable. When running tests, you should skip the unstable ones by running `dotnet test --filter "TestCategory!=FailsInCloudTest"`.
34
+
**IMPORTANT**: This repository uses Microsoft.Testing.Platform (MTP v2) with xunit v3. Traditional `--filter` syntax does NOT work. Use the options below instead.
35
+
36
+
* There should generally be one test project (under the `test` directory) per shipping project (under the `src` directory). Test projects are named after the project being tested with a `.Tests` suffix.
37
+
* Tests use xunit v3 with Microsoft.Testing.Platform (MTP v2). Traditional VSTest `--filter` syntax does NOT work.
38
+
* Some tests are known to be unstable. When running tests, you should skip the unstable ones by using `-- --filter-not-trait "FailsInCloudTest=true"`.
50
39
* Write tests that cover both happy path and edge cases.
51
40
* Ensure all new functionality is covered by tests.
52
41
42
+
### Running Tests
43
+
44
+
**Run all tests**:
45
+
```bash
46
+
dotnet test --no-build -c Release
47
+
```
48
+
49
+
**Run tests for a specific test project**:
50
+
```bash
51
+
dotnet test --project test/Library.Tests/Library.Tests.csproj --no-build -c Release
52
+
```
53
+
54
+
**Run a single test method**:
55
+
```bash
56
+
dotnet test --project test/Library.Tests/Library.Tests.csproj --no-build -c Release -- --filter-method ClassName.MethodName
57
+
```
58
+
59
+
**Run all tests in a test class**:
60
+
```bash
61
+
dotnet test --project test/Library.Tests/Library.Tests.csproj --no-build -c Release -- --filter-class ClassName
62
+
```
63
+
64
+
**Run tests with wildcard matching** (supports wildcards at beginning and/or end):
65
+
```bash
66
+
dotnet test --project test/Library.Tests/Library.Tests.csproj --no-build -c Release -- --filter-method "*Pattern*"
67
+
```
68
+
69
+
**Run tests with a specific trait** (equivalent to category filtering):
70
+
```bash
71
+
dotnet test --project test/Library.Tests/Library.Tests.csproj --no-build -c Release -- --filter-trait "TraitName=value"
72
+
```
73
+
74
+
**Exclude tests with a specific trait** (skip unstable tests):
75
+
```bash
76
+
dotnet test --project test/Library.Tests/Library.Tests.csproj --no-build -c Release -- --filter-not-trait "TestCategory=FailsInCloudTest"
77
+
```
78
+
79
+
**Run tests for a specific framework only**:
80
+
```bash
81
+
dotnet test --project test/Library.Tests/Library.Tests.csproj --no-build -c Release --framework net9.0
82
+
```
83
+
84
+
**List all available tests without running them**:
85
+
```bash
86
+
cd test/Library.Tests
87
+
dotnet run --no-build -c Release --framework net9.0 -- --list-tests
88
+
```
89
+
90
+
**Key points about test filtering with MTP v2 / xunit v3**:
91
+
- Options after `--` are passed to the test runner, not to `dotnet test`
92
+
- Use `--filter-method`, `--filter-class`, `--filter-namespace` for simple filtering
93
+
- Use `--filter-trait` and `--filter-not-trait` for trait-based filtering (replaces `--filter "TestCategory=..."`)
94
+
- Traditional VSTest `--filter` expressions do NOT work
95
+
- Wildcards `*` are supported at the beginning and/or end of filter values
96
+
- Multiple simple filters of the same type use OR logic, different types combine with AND
97
+
- See `--help` for query filter language for advanced scenarios
98
+
53
99
## Coding Style
54
100
55
101
* Honor StyleCop rules and fix any reported build warnings *after* getting tests to pass.
This file will describe significant changes in Library.Template as they are introduced, especially if they require special consideration when merging updates into existing repos.
4
+
This file is referenced by update-library-template.prompt.md and should remain in place to facilitate future merges, whether done manually or by AI.
5
+
6
+
## Solution rename
7
+
8
+
Never leave a Library.slnx file in the repository.
9
+
You might even see one there even though this particular merge didn't bring it in.
10
+
This can be an artifact of having renamed Library.sln to Library.slnx in the template repo, but ultimately the receiving repo should have only one .sln or .slnx file, with a better name than `Library`.
11
+
Delete any `Library.slnx` that you see.
12
+
Migrate an `.sln` in the repo root to `.slnx` using this command:
13
+
14
+
```ps1
15
+
dotnet solution EXISTING.sln migrate
16
+
```
17
+
18
+
This will create an EXISTING.slnx file. `git add` that file, then `git rm` the old `.sln` file.
19
+
Sometimes a repo will reference the sln filename in a script or doc somewhere.
20
+
Search the repo for such references and update them to the slnx file.
3. Validate the changes, as described in the validation section below.
10
+
4. Committing your changes (if applicable).
11
+
12
+
## Conflict resolution policy
13
+
14
+
There may be special notes in `.github/prompts/template-release-notes.md` that describe special considerations for certain files or scenarios to help you resolve conflicts appropriately.
15
+
Always refer to that file before proceeding.
16
+
In particular, focus on the *incoming* part of the file, since it represents the changes from the Library.Template that you are merging into your repo.
17
+
18
+
Also consider that some repos choose to reject certain Library.Template patterns.
19
+
For example the template uses MTPv2 for test projects, but a repo might have chosen not to adopt that.
20
+
When resolving merge conflicts, consider whether it looks like the relevant code file is older than it should be given the changes the template is bringing in.
21
+
Ask the user when in doubt as to whether the conflict should be resolved in favor of 'catching up' with the template or keeping the current changes.
22
+
23
+
Use #runSubagent to analyze and resolve merge conflicts across files in parallel.
24
+
25
+
### Keep Current files
26
+
27
+
Conflicts in the following files should always be resolved by keeping the current version (i.e. discard incoming changes):
28
+
29
+
* README.md
30
+
31
+
### Deleted files
32
+
33
+
Very typically, when the incoming change is to a file that was deleted locally, the correct resolution is to re-delete the file.
34
+
35
+
In some cases however, the deleted file may have incoming changes that should be applied to other files.
36
+
The `test/Library.Tests/Library.Tests.csproj` file is very typical of this.
37
+
Changes to this file should very typically be applied to any and all test projects in the repo.
38
+
You are responsible for doing this in addition to re-deleting this template file.
39
+
40
+
## Validation
41
+
42
+
Validate the merge result (after resolving any conflicts, if applicable).
43
+
Use #runSubagent for each step.
44
+
45
+
1. Verify that `dotnet restore` succeeds. Fix any issues that come up.
46
+
2. Verify that `dotnet build` succeeds.
47
+
3. Verify that tests succeed by running `tools/dotnet-test-cloud.ps1`.
48
+
49
+
While these validations are described using `dotnet` CLI commands, some repos require using full msbuild.exe.
50
+
You can detect this by checking the `azure-pipelines/dotnet.yml` or `.github/workflows/build.yml` files for use of one or the other tool.
51
+
52
+
You are *not* responsible for fixing issues that the merge did not cause.
53
+
If validation fails for reasons that seem unrelated to the changes brought in by the merge, advise the user and ask how they'd like you to proceed.
54
+
That said, sometimes merges will bring in SDK or dependency updates that can cause breaks in seemingly unrelated areas.
55
+
In such cases, you should investigate and solve the issues as needed.
56
+
57
+
## Committing your changes
58
+
59
+
If you have to make any changes for validations to pass, consider whether they qualify as a bad merge conflict resolution or more of a novel change that you're making to work with the Library.Template update.
60
+
Merge conflict resolution fixes ideally get amended into the merge commit, while novel changes would go into a novel commit after the merge commit.
61
+
62
+
Always author your commits using `git commit --author "🤖 Copilot <no-reply@github.com>"` (and possibly other parameters).
63
+
Describe the nature of the merge conflicts you encountered and how you resolved them in your commit message.
64
+
65
+
Later, if asked to review pull request validation breaks, always author a fresh commit with each fix that you push, unless the user directs you to do otherwise.
0 commit comments