Skip to content

Commit c9b5af9

Browse files
tigtig
authored
Fix/agents instructions (gui-cs#4590)
* New workflow that will analyze the dmp file on the macos runner. * updated agents * Revise XML documentation rules for clarity and consistency Clarified XML documentation rules and improved wording for consistency. * Updates API docs. * Fixes IValue namespce * Deleted old files
1 parent 12917e5 commit c9b5af9

19 files changed

+751
-1224
lines changed

‎.claude/rules/api-documentation.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# API Documentation Requirements
2+
3+
**Source:** [CONTRIBUTING.md - API Documentation Requirements](../../CONTRIBUTING.md#api-documentation-requirements)
4+
5+
## XML Documentation Rules
6+
7+
- **All public APIs MUST have XML documentation:**
8+
9+
### Required Elements
10+
11+
1. **`<summary>` tag** - Clear, concise description
12+
- Use proper English and grammar
13+
- Clear, concise, complete
14+
- Use imperative mood ("Gets the value" not "Get the value")
15+
- Use infinitive-of-purpose + imperative pattern for instructional sentences
16+
17+
2. **`<see cref=""/>` for cross-references**
18+
- Link to related types, methods, properties
19+
- Example: `<see cref="View.Draw"/>` or `<see cref="Application"/>`
20+
21+
3. **`<remarks>` for context**
22+
- Add only if obviously essential to do so
23+
- Add important notes, warnings, or additional context
24+
- Explain non-obvious behavior
25+
26+
5. **`<example>` for non-obvious usage**
27+
- Include code examples ONLY when usage isn't immediately clear
28+
- Use working, compilable code snippets that strictly adhear to the coding/syntax style
29+
30+
6. **Complex topics → `docfx/docs/*.md` files**
31+
- For architecture concepts, patterns, or deep dives
32+
- Link from XML docs to conceptual docs
33+
34+
## Documentation Style
35+
36+
### Imperative Mood
37+
```csharp
38+
// ✅ CORRECT
39+
/// <summary>Gets or sets the width of the view.</summary>
40+
41+
// ❌ WRONG
42+
/// <summary>Get or set the width of the view.</summary>
43+
```
44+
45+
### Clear Cross-References
46+
```csharp
47+
// ✅ CORRECT
48+
/// <summary>
49+
/// Draws the view. See <see cref="OnDrawContent"/> for customizing the drawing behavior.
50+
/// </summary>
51+
52+
// ❌ WRONG
53+
/// <summary>Draws the view. Override OnDrawContent to customize.</summary>
54+
```
55+
56+
### Examples for Complex APIs
57+
```csharp
58+
/// <summary>
59+
/// Creates a new <see cref="Dialog"/> with the specified buttons.
60+
/// </summary>
61+
/// <example>
62+
/// <code>
63+
/// Dialog dialog = new () {
64+
/// Title = "Confirm",
65+
/// Buttons = [new Button ("OK"), new Button ("Cancel")]
66+
/// };
67+
/// Application.Run (dialog);
68+
/// </code>
69+
/// </example>
70+
```
71+
72+
## When to Create Conceptual Docs
73+
74+
Create a new file in `docfx/docs/` when:
75+
76+
- Explaining architecture concepts (e.g., `application.md`, `layout.md`)
77+
- Documenting patterns (e.g., `cancellable-work-pattern.md`)
78+
- Providing tutorials or guides
79+
- Content is too long for XML documentation
80+
81+
Link from XML docs to conceptual docs:
82+
```csharp
83+
/// <summary>
84+
/// Manages the application lifecycle. See the
85+
/// <a href="../docs/application.md">Application Deep Dive</a> for details.
86+
/// </summary>
87+
```
88+
89+
## Documentation is the Spec
90+
91+
**Code Style Tenet #5:** Documentation is the specification.
92+
93+
- API documentation defines the contract
94+
- Implementation must match documentation
95+
- When docs and code conflict, fix the code or update the docs
96+
- Keep documentation synchronized with code changes

‎.claude/rules/testing-patterns.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# Testing Patterns
2+
3+
**Source:** [CONTRIBUTING.md - Testing Requirements](../../CONTRIBUTING.md#testing-requirements)
4+
5+
## Code Coverage
6+
7+
- **Never decrease code coverage** - PRs must maintain or increase coverage
8+
- Target: **70%+ coverage** for new code
9+
- Coverage collection:
10+
- Centralized in `TestResults/` directory at repository root
11+
- Collected only on Linux (ubuntu-latest) runners in CI for performance
12+
- Windows and macOS runners skip coverage collection to reduce execution time
13+
- Coverage reports uploaded to Codecov automatically from Linux runner
14+
- CI monitors coverage on each PR
15+
16+
## Test Patterns
17+
18+
**⚠️ AI-created tests MUST follow these patterns exactly:**
19+
20+
1. **Add comment indicating the test was AI generated**
21+
- Example: `// CoPilot - ChatGPT v4`
22+
23+
2. **Make tests granular**
24+
- Each test should cover smallest area possible
25+
26+
3. **Follow existing test patterns**
27+
- Study tests in respective test projects before writing new ones
28+
29+
4. **Avoid adding new tests to `UnitTests` Project**
30+
- Make them parallelizable and add them to `UnitTestsParallelizable`
31+
32+
5. **Avoid static dependencies**
33+
- DO NOT use the legacy/static `Application` API or `ConfigurationManager` in tests unless the tests explicitly test related functionality
34+
35+
6. **Don't use `[AutoInitShutdown]` or `[SetupFakeApplication]`**
36+
- Legacy pattern, being phased out
37+
38+
## Test Projects
39+
40+
### 1. Non-Parallel Tests (`Tests/UnitTests/`)
41+
42+
**When to use:**
43+
- Testing functionality that depends on static state
44+
- Testing `Application.Init` and `Application.Shutdown`
45+
46+
**Characteristics:**
47+
- ~10 min timeout
48+
- Uses `Application.Init` and static state
49+
- Cannot run in parallel
50+
- Includes `--blame` flags for crash diagnostics
51+
52+
**Command:**
53+
```bash
54+
dotnet test Tests/UnitTests --no-build --verbosity normal
55+
```
56+
57+
### 2. Parallel Tests (`Tests/UnitTestsParallelizable/`) - **PREFERRED**
58+
59+
**When to use:**
60+
- All new tests should go here unless they explicitly need static state
61+
62+
**Characteristics:**
63+
- ~10 min timeout
64+
- No dependencies on static state
65+
- Can run concurrently
66+
- Faster execution
67+
68+
**Command:**
69+
```bash
70+
dotnet test Tests/UnitTestsParallelizable --no-build --verbosity normal
71+
```
72+
73+
### 3. Integration Tests (`Tests/IntegrationTests/`)
74+
75+
**When to use:**
76+
- Testing cross-component interactions
77+
- End-to-end scenarios
78+
79+
**Command:**
80+
```bash
81+
dotnet test Tests/IntegrationTests --no-build --verbosity normal
82+
```
83+
84+
## Test Configuration Files
85+
86+
- `xunit.runner.json` - xUnit configuration
87+
- `coverlet.runsettings` - Coverage settings (OpenCover format)
88+
89+
## Example Test Pattern
90+
91+
```csharp
92+
// CoPilot - ChatGPT v4
93+
[Fact]
94+
public void MyFeature_ShouldBehaveProperly_WhenConditionMet ()
95+
{
96+
// Arrange
97+
View view = new () { Width = 10, Height = 5 };
98+
99+
// Act
100+
view.Draw ();
101+
102+
// Assert
103+
Assert.Equal (10, view.Width);
104+
}
105+
```

‎.claude/workflows/build-test-workflow.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# Build and Test Workflow
2+
3+
**Source:** [CONTRIBUTING.md - Building and Testing](../../CONTRIBUTING.md#building-and-testing)
4+
5+
## Required Tools
6+
7+
- **.NET SDK**: 8.0.0 (see `global.json`)
8+
- **Runtime**: .NET 8.x (latest GA)
9+
- **Optional**: ReSharper/Rider for code formatting (honor `.editorconfig` and `Terminal.sln.DotSettings`)
10+
11+
## Build Commands
12+
13+
**⚠️ ALWAYS run these commands from the repository root**
14+
15+
### 1. Restore Packages (Required First)
16+
17+
**Time:** ~15-20 seconds
18+
19+
```bash
20+
dotnet restore
21+
```
22+
23+
**Must run before building.** Downloads all NuGet dependencies.
24+
25+
### 2. Build Solution (Debug)
26+
27+
**Time:** ~50 seconds
28+
29+
```bash
30+
dotnet build --configuration Debug --no-restore
31+
```
32+
33+
**Expected output:**
34+
- ~326 warnings (nullable reference warnings, unused variables, etc.) - **these are normal**
35+
- **0 errors expected**
36+
37+
### 3. Build Release (For Packaging)
38+
39+
```bash
40+
dotnet build --configuration Release --no-restore
41+
```
42+
43+
## Test Commands
44+
45+
### Run Non-Parallel Tests
46+
47+
**Time:** ~10 min timeout
48+
49+
```bash
50+
dotnet test Tests/UnitTests --no-build --verbosity normal
51+
```
52+
53+
- Uses `Application.Init` and static state
54+
- Cannot run in parallel
55+
- Includes `--blame` flags for crash diagnostics
56+
57+
### Run Parallel Tests (Preferred)
58+
59+
**Time:** ~10 min timeout
60+
61+
```bash
62+
dotnet test Tests/UnitTestsParallelizable --no-build --verbosity normal
63+
```
64+
65+
- No dependencies on static state
66+
- **Preferred for new tests**
67+
- Faster execution
68+
69+
### Run Integration Tests
70+
71+
```bash
72+
dotnet test Tests/IntegrationTests --no-build --verbosity normal
73+
```
74+
75+
### Run All Tests
76+
77+
```bash
78+
dotnet test --no-build --verbosity normal
79+
```
80+
81+
## Common Build Issues
82+
83+
### Issue: NativeAot/SelfContained Build Failures
84+
85+
**Solution:** Restore these projects explicitly:
86+
87+
```bash
88+
dotnet restore ./Examples/NativeAot/NativeAot.csproj -f
89+
dotnet restore ./Examples/SelfContained/SelfContained.csproj -f
90+
```
91+
92+
## Build Order Best Practice
93+
94+
**For clean builds, always run in this order:**
95+
96+
```bash
97+
dotnet restore && dotnet build --no-restore && dotnet test --no-build
98+
```
99+
100+
This ensures:
101+
1. Packages are downloaded first
102+
2. Build uses restored packages
103+
3. Tests run against built assemblies
104+
4. Minimal rebuild overhead
105+
106+
## Warning Management
107+
108+
**⚠️ CRITICAL - PRs must not introduce any new warnings**
109+
110+
- Any file modified in a PR that currently generates warnings **MUST** be fixed to remove those warnings
111+
- **Exception:** Warnings caused by `[Obsolete]` attributes can remain
112+
- **Action:** Before submitting a PR, verify your changes don't add new warnings and fix any warnings in files you modify

0 commit comments

Comments
 (0)