Skip to content

Add investigation & debugging practices to copilot-instructions #11141

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jonathanpeppers merged 3 commits into from
Apr 17, 2026
+24 −1
Merged

Add investigation & debugging practices to copilot-instructions #11141

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2db045a
Add investigation & debugging practices to copilot-instructions
simonrozsival Apr 17, 2026
cd7f66f
Address review feedback: tighten verbosity, add Windows note, consoli…
jonathanpeppers Apr 17, 2026
5e83d7c
Address Copilot review feedback: fix _AndroidTypeMapImplementation va…
jonathanpeppers Apr 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 24 additions & 1 deletion .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -199,8 +199,31 @@ This pattern ensures proper encoding, timestamps, and file attributes are handle
3. For deep .binlog analysis, use the `azdo-build-investigator` skill.
4. Only after the skill confirms no Azure DevOps failures should you report CI as passing.

## Investigation & Debugging Practices

When diagnosing runtime, build, or test failures, follow these practices. They exist because the .NET ↔ JNI ↔ C++ ↔ generated-native stack is loosely coupled and static reasoning alone is unreliable.

- **Reproduce CI failures locally — do not iterate through CI.** A clean local test cycle is minutes; a CI iteration is hours. Run device tests the same way CI does:
```bash
make prepare && make all CONFIGURATION=Release
Comment thread
jonathanpeppers marked this conversation as resolved.
./dotnet-local.sh build tests/Mono.Android-Tests/Mono.Android-Tests/Mono.Android.NET-Tests.csproj \
-t:RunTestApp -c Release \
-p:_AndroidTypeMapImplementation=<llvm-ir|managed|trimmable> \
-p:UseMonoRuntime=<true|false>
```
On Windows, use `build.cmd` and `dotnet-local.cmd` instead of `make`/`dotnet-local.sh`.
Results land in `TestResult-Mono.Android.NET_Tests-*.xml` at the repo root.

- **When the build gets into a weird state, nuke `bin/` and `obj/` and rebuild from scratch.** Stale incremental output causes phantom errors. See **Troubleshooting → Build** below.

- **Verify code paths with logging, not reasoning.** Add `log_warn (LOG_DEFAULT, "..."sv, ...)` in C++ or `Android.Util.Log` in C#, rebuild, re-run, and check `adb logcat -d`. If your log never fires, your call-graph assumption is wrong.

- **Decompile the produced `.dll` before blaming runtime.** Use `ilspycmd` or `ildasm` to inspect the actual generated IL/metadata. A missing attribute or misnamed type in generator output cascades into opaque runtime failures.

- **`am instrument` going silent means it crashed, not hung.** Check `adb logcat -d | grep -E 'FATAL|tombstone|signal'` for a native crash dump. Do not wait for a CI timeout to "confirm" a hang that was really an instant crash.

## Troubleshooting
- **Build:** Clean `bin/`+`obj/`, check Android SDK/NDK, `make clean`
- **Build:** Clean `bin/`+`obj/`, check Android SDK/NDK, `make clean && make prepare && make all`
- **MSBuild:** Test in isolation, validate inputs
- **Device:** Use update directories for rapid Debug iteration
- **Performance:** See `../Documentation/guides/profiling.md` and `../Documentation/guides/tracing.md`