Skip to content

Commit fcb028b

Browse files
Copilotnoahfalkhoyosjs
authored
Create AGENTS.md with standard guidance for AI agents (#5609)
- [x] Understand the repository structure and context - [x] Create AGENTS.md file with standard guidance for AI agents - [x] Include repository-specific information (build, test, architecture) - [x] Include coding standards and conventions - [x] Include testing guidelines - [x] Verify the file is properly formatted and complete - [x] Update build options to use single dash for consistency - [x] Merge EditorConfig section with C# Code Style section - [x] Add Development Workflow section - [x] Remove .NET Runtime Repository link from Resources - [x] Refine guidance on making changes to balance minimal changes with code clarity <!-- START COPILOT CODING AGENT SUFFIX --> <details> <summary>Original prompt</summary> > > ---- > > *This section details on the original issue you should resolve* > > <issue_title>Create AGENTS.md</issue_title> > <issue_description>As we use copilot more we won't want to repeat the same general guidance again and again on every PR. Instead we should have an AGENTS.md file that provides this standard information in a reusable form.</issue_description> > > ## Comments on the Issue (you are @copilot in this section) > > <comments> > </comments> > </details> Fixes #5608 <!-- START COPILOT CODING AGENT TIPS --> --- ✨ Let Copilot coding agent [set things up for you](https://github.com/dotnet/diagnostics/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot) — coding agent works faster and does higher quality work when set up for your repo. --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: noahfalk <6243776+noahfalk@users.noreply.github.com> Co-authored-by: hoyosjs <19413848+hoyosjs@users.noreply.github.com>
1 parent fee8d69 commit fcb028b

File tree

2 files changed

+321
-0
lines changed

2 files changed

+321
-0
lines changed

‎.github/workflows/copilot-setup-steps.yml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
name: "Copilot Setup Steps"
2+
3+
# Allow testing of the setup steps from your repository's "Actions" tab.
4+
on: workflow_dispatch
5+
6+
jobs:
7+
# The job MUST be called `copilot-setup-steps` or it will not be picked up by Copilot.
8+
# See https://docs.github.com/en/copilot/customizing-copilot/customizing-the-development-environment-for-copilot-coding-agent
9+
copilot-setup-steps:
10+
runs-on: 8-core-ubuntu-latest
11+
12+
permissions:
13+
contents: read
14+
15+
# You can define any steps you want, and they will run before the agent starts.
16+
# If you do not check out your code, Copilot will do this for you.
17+
steps:
18+
- uses: actions/checkout@v5
19+
20+
- name: Install Dependencies
21+
run: |
22+
sudo ./eng/common/native/install-dependencies.sh && \
23+
sudo apt-get install -qq -y \
24+
curl
25+
26+
- name: Restore solution
27+
run: ./build.sh -restore
28+
29+
- name: Put dotnet on the path
30+
run: echo "PATH=$PWD/.dotnet:$PATH" >> $GITHUB_ENV
31+
32+
- name: Run dotnet info
33+
run: dotnet --info
34+
35+
- name: Build clr+libs
36+
run: ./build.sh

‎AGENTS.md‎

Lines changed: 285 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,285 @@
1+
# Agent Guidelines for .NET Diagnostics Repository
2+
3+
This document provides standard guidance for AI agents and automated tools working on the .NET Diagnostics repository. Following these guidelines will help ensure consistency and quality across contributions.
4+
5+
## Repository Overview
6+
7+
The .NET Diagnostics repository contains diagnostic tools and libraries for .NET Core, including:
8+
9+
- **SOS**: The Son of Strike debugger extension
10+
- **dotnet-dump**: Dump collection and analysis utility
11+
- **dotnet-gcdump**: Heap analysis tool
12+
- **dotnet-trace**: Event collection tool
13+
- **dotnet-counters**: Performance counter monitoring tool
14+
- **Diagnostic libraries**: Client libraries and services for diagnostics
15+
16+
## Build System
17+
18+
### Building the Repository
19+
20+
The repository uses a cross-platform build system:
21+
22+
**Linux/macOS:**
23+
```bash
24+
./build.sh
25+
```
26+
27+
**Windows:**
28+
```cmd
29+
Build.cmd
30+
```
31+
32+
### Build Scripts Location
33+
- Main build scripts: `build.sh` / `Build.cmd` at repository root
34+
- Actual build logic: `eng/build.sh` / `eng/Build.cmd`
35+
- Build configuration: `build.proj`, `Directory.Build.props`, `Directory.Build.targets`
36+
37+
### Common Build Options
38+
- `-configuration <Debug|Release>`: Build configuration (default: Debug)
39+
- `-architecture <x64|x86|arm|arm64>`: Target architecture
40+
- `-restore`: Restore dependencies before building
41+
- `-build`: Build the repository
42+
- `-rebuild`: Clean and rebuild
43+
- `-test`: Run tests after building
44+
45+
## Testing
46+
47+
### Running Tests
48+
49+
**Linux/macOS:**
50+
```bash
51+
./test.sh
52+
```
53+
54+
**Windows:**
55+
```cmd
56+
Test.cmd
57+
```
58+
59+
The test script runs all tests in the repository. Test projects are located in the `src/tests` directory.
60+
61+
### Test Organization
62+
- Unit tests are typically in `*.Tests` projects
63+
- Integration tests may be in separate test projects
64+
- Test helpers are in `Microsoft.Diagnostics.TestHelpers`
65+
66+
## Project Structure
67+
68+
```
69+
/src
70+
├── Microsoft.Diagnostics.DebugServices # Debug service interfaces
71+
├── Microsoft.Diagnostics.DebugServices.Implementation # Debug service implementations
72+
├── Microsoft.Diagnostics.ExtensionCommands # SOS extension commands
73+
├── Microsoft.Diagnostics.Monitoring # Monitoring libraries
74+
├── Microsoft.Diagnostics.NETCore.Client # Diagnostic client library
75+
├── Microsoft.Diagnostics.Repl # REPL infrastructure
76+
├── Microsoft.FileFormats # File format parsers
77+
├── Microsoft.SymbolStore # Symbol store implementation
78+
├── SOS # SOS debugger extension
79+
├── Tools # Command-line tools (dump, trace, counters, gcdump)
80+
├── tests # Test projects
81+
└── shared # Shared native code
82+
83+
/documentation # Documentation files
84+
/eng # Engineering/build infrastructure
85+
```
86+
87+
## Coding Standards
88+
89+
### C# Code Style
90+
91+
The repository follows standard .NET coding conventions defined in the `.editorconfig` file at the root. This is a **must** for C# code. Ensure your changes conform to these settings:
92+
93+
1. **Indentation**: 4 spaces (no tabs)
94+
2. **Line endings**: LF on Linux/macOS, CRLF on Windows
95+
3. **Braces**: Opening braces on new lines for types, methods, properties, control blocks
96+
4. **Naming**:
97+
- PascalCase for types, methods, properties, public fields
98+
- camelCase for local variables, parameters, private fields
99+
- `_camelCase` for private instance fields (with underscore prefix)
100+
5. **File organization**: One type per file, filename matches type name
101+
6. **Additional EditorConfig rules**:
102+
- Trim trailing whitespace
103+
- Insert final newline
104+
- Follow C# new line and indentation preferences
105+
106+
### Native Code (C/C++)
107+
108+
Native code follows similar conventions:
109+
- 4 spaces for indentation
110+
- Braces on same line for control structures in C++
111+
- Use clear, descriptive names
112+
- Follow existing patterns in the codebase
113+
114+
## Making Changes
115+
116+
### General Guidelines
117+
118+
1. **Surgical changes**: Make the smallest possible changes to address the issue. Focus on solving a single problem without addressing unrelated concerns. Balance minimal code changes with preserving overall code clarity and simplicity
119+
2. **Preserve existing behavior**: Don't break working functionality unless explicitly required
120+
3. **Follow existing patterns**: Match the style and structure of surrounding code
121+
4. **Test thoroughly**: Run builds and tests to verify changes
122+
5. **Update documentation**: If making significant changes, update relevant documentation
123+
124+
### Before Making Changes
125+
126+
1. Run a clean build to ensure the current state is valid:
127+
```bash
128+
./build.sh # or Build.cmd on Windows
129+
```
130+
131+
2. Run tests to understand the baseline:
132+
```bash
133+
./test.sh # or Test.cmd on Windows
134+
```
135+
136+
3. Understand the area you're working on:
137+
- Read related source files
138+
- Review existing tests
139+
- Check documentation in `/documentation`
140+
141+
### After Making Changes
142+
143+
1. **Build**: Ensure your changes compile without errors or new warnings
144+
2. **Test**: Run relevant tests to verify functionality
145+
3. **Code style**: Verify changes match the repository's coding standards
146+
4. **Documentation**: Update if your changes affect public APIs or behavior
147+
148+
## Development Workflow
149+
150+
### Typical Workflow
151+
152+
1. **Create a branch**: Create a feature branch from `main` with a descriptive name
153+
2. **Make changes**: Implement your changes following the coding standards
154+
3. **Build locally**: Run `./build.sh` (or `Build.cmd` on Windows) to ensure the code compiles
155+
4. **Run tests**: Execute `./test.sh` (or `Test.cmd` on Windows) to verify functionality
156+
5. **Commit changes**: Make small, logical commits with clear commit messages
157+
6. **Push to remote**: Push your branch to the remote repository
158+
7. **Create pull request**: Open a PR with a clear description of your changes
159+
8. **Address feedback**: Respond to review comments and make necessary updates
160+
9. **Merge**: Once approved, the PR will be merged to `main`
161+
162+
### Iterative Development
163+
164+
- Make small, incremental changes rather than large, sweeping modifications
165+
- Test frequently to catch issues early
166+
- Commit logical units of work separately
167+
- Keep the build and tests passing at each commit when possible
168+
169+
### Pull Request Guidelines
170+
171+
- **Title**: Use a clear, descriptive title that summarizes the change
172+
- **Description**: Explain what changed, why it changed, and how to test it
173+
- **Link issues**: Reference related issues using "Fixes #1234" or "Addresses #1234"
174+
- **Keep focused**: Each PR should address a single concern or feature
175+
- **Respond promptly**: Address review feedback in a timely manner
176+
177+
## Common Patterns
178+
179+
### Solution Files
180+
181+
The main solution file is `build.sln` at the root. This file is generated from `build.proj` and can be regenerated using:
182+
```bash
183+
./eng/generate-sln.sh
184+
```
185+
186+
### Dependency Management
187+
188+
- NuGet packages: `eng/Versions.props` defines package versions
189+
- Project references: Use relative paths in `.csproj` files
190+
- Native dependencies: Handled through CMake
191+
192+
### Platform-Specific Code
193+
194+
The repository supports multiple platforms (Windows, Linux, macOS, FreeBSD, NetBSD):
195+
- Use conditional compilation (`#if`, `#ifdef`) for platform-specific code
196+
- Leverage .NET's platform detection APIs
197+
- Keep platform-specific code minimal and isolated
198+
199+
## Debugging and Diagnostics
200+
201+
### Loading in IDEs
202+
203+
**Visual Studio Code:**
204+
- Open the repository root folder
205+
- Load `build.sln` for better IntelliSense
206+
- Use the provided launch configurations in `.vscode`
207+
208+
**Visual Studio:**
209+
```cmd
210+
start-vs.cmd
211+
```
212+
213+
### Common Issues
214+
215+
1. **Build failures**: Ensure all prerequisites are installed (see documentation/building/)
216+
2. **Test failures**: Some tests may require specific runtime versions or configurations
217+
3. **Native component issues**: Check CMake output for missing dependencies
218+
219+
## Dependencies and Security
220+
221+
### Adding Dependencies
222+
223+
1. **NuGet packages**: Add to `eng/Versions.props` with appropriate version
224+
2. **Security**: Be mindful of security implications when adding dependencies
225+
3. **Licensing**: Ensure new dependencies are compatible with MIT license
226+
4. **Minimize dependencies**: Only add when necessary
227+
228+
### Security Considerations
229+
230+
- Never commit secrets or credentials
231+
- Follow secure coding practices (input validation, proper error handling)
232+
- Be cautious with native interop and memory management
233+
- Review security implications of changes
234+
235+
## Testing Philosophy
236+
237+
1. **Write tests for new functionality**: New features should include tests
238+
2. **Don't remove existing tests**: Tests verify important functionality
239+
3. **Fix test failures related to your changes**: Don't ignore failing tests
240+
4. **Maintain test quality**: Tests should be clear, focused, and maintainable
241+
242+
## Documentation
243+
244+
### When to Update Documentation
245+
246+
- Adding new tools or features
247+
- Changing public APIs
248+
- Modifying build or test procedures
249+
- Adding new dependencies or requirements
250+
251+
### Documentation Locations
252+
253+
- Tool documentation: `/documentation/*-instructions.md`
254+
- Building instructions: `/documentation/building/`
255+
- Design documents: `/documentation/design-docs/`
256+
- README: `/README.md`
257+
258+
## Git and Version Control
259+
260+
### Branch Strategy
261+
262+
- Main development: `main` branch
263+
- Feature branches: Use descriptive names
264+
- Pull requests: Required for all changes
265+
266+
### Commit Messages
267+
268+
- First line: Brief summary (50 characters or less)
269+
- Blank line, then detailed description if needed
270+
- Reference issues: "Fixes #1234" or "Addresses #1234"
271+
272+
## Resources
273+
274+
- [Building on Linux](documentation/building/linux-instructions.md)
275+
- [Building on Windows](documentation/building/windows-instructions.md)
276+
- [Building on macOS](documentation/building/osx-instructions.md)
277+
- [FAQ](documentation/FAQ.md)
278+
279+
## Questions and Support
280+
281+
If you encounter issues or have questions:
282+
1. Check existing documentation in `/documentation`
283+
2. Review closed issues and pull requests for similar problems
284+
3. Consult the [FAQ](documentation/FAQ.md)
285+
4. Ask in the issue or pull request you're working on

0 commit comments

Comments
 (0)