From 9f8cd57fe82541060713608e153cebdb5b4ce5b6 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 30 Aug 2025 11:18:51 +0000 Subject: [PATCH 1/5] Initial plan From 5a0cdd8ffd6311a9ac54f771917e7616be4bdef1 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 30 Aug 2025 11:29:11 +0000 Subject: [PATCH 2/5] Add comprehensive GitHub Copilot instructions for development workflow Co-authored-by: kieronlanning <5364423+kieronlanning@users.noreply.github.com> --- .github/copilot-instructions.md | 148 ++++++++++++++++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000..84978606 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,148 @@ +# Purview Telemetry Source Generator + +Purview Telemetry Source Generator is a .NET 9.0 source generator that generates [`ActivitySource`](https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.activitysource), [`ILogger`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.logging.ilogger), and [`Metrics`](https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.metrics) based telemetry from methods you define on an interface. + +Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here. + +## Working Effectively + +### Prerequisites +Install these exact dependencies in order: +- Install .NET 9.0.200 SDK: `curl -sSL https://dot.net/v1/dotnet-install.sh | bash -s -- --version 9.0.200` +- Install .NET 9.0 runtime: `curl -sSL https://dot.net/v1/dotnet-install.sh | bash -s -- --runtime dotnet --version 9.0.0` +- Install Bun: `curl -fsSL https://bun.sh/install | bash` +- Set environment variables: `export PATH=$HOME/.bun/bin:$HOME/.dotnet:$PATH && export DOTNET_ROOT=$HOME/.dotnet` + +### Bootstrap, Build, and Test +Bootstrap and build the repository: +- `make build` -- builds the main source generator and integration tests. Takes 26 seconds. NEVER CANCEL. Set timeout to 60+ minutes. +- `make test` -- runs 282 integration tests. Takes 42 seconds. NEVER CANCEL. Set timeout to 60+ minutes. +- `make format` -- formats code according to .editorconfig rules. Takes 21 seconds. NEVER CANCEL. Set timeout to 30+ minutes. + +Alternative direct commands (use environment variables above): +- `dotnet build ./src/Purview.Telemetry.SourceGenerator.slnx --configuration Release` +- `dotnet test ./src/Purview.Telemetry.SourceGenerator.slnx --configuration Release` +- `dotnet format ./src/` + +### Build and Test Sample Application +The sample application demonstrates the source generator in action: +- `cd samples/SampleApp && dotnet build --configuration Release` -- takes 19 seconds. NEVER CANCEL. Set timeout to 30+ minutes. +- `cd samples/SampleApp && dotnet test --configuration Release` -- runs 8 tests, takes 3 seconds. + +### Package Creation +- `make pack` -- creates NuGet package with current version from package.json +- `make version` -- displays current version (currently 3.2.4) + +## Validation + +### Manual Validation Requirements +Always manually validate changes to the source generator: +- ALWAYS run `make build && make test` after making any changes to the source generator code +- ALWAYS build and test the sample application: `cd samples/SampleApp && dotnet build --configuration Release && dotnet test --configuration Release` +- ALWAYS run `make format` before committing to ensure code formatting compliance +- Test actual source generator functionality by examining generated files in the sample project (EmitCompilerGeneratedFiles is enabled) + +### Functional Testing Scenarios +Test these scenarios when modifying the source generator: +- **Interface to Implementation Generation**: Modify an interface in `samples/SampleApp/SampleApp.Host/APIs/` and verify generated telemetry code appears +- **Activity Generation**: Test ActivitySource generation by adding methods with activity attributes +- **Logging Generation**: Test ILogger generation by adding methods with logging attributes +- **Metrics Generation**: Test metrics generation by adding methods with metrics attributes +- **Integration Test Coverage**: Verify new functionality is covered by tests in `src/Purview.Telemetry.SourceGenerator.IntegrationTests/` + +### CI Validation +Always run these validation steps before committing: +- `make format` (takes 21 seconds) +- `make build` (takes 26 seconds) +- `make test` (takes 42 seconds) +- Sample app build and test (takes 22 seconds total) + +The CI pipeline (`./github/workflows/ci.yml`) runs the same dotnet restore → build → test workflow. + +## Common Tasks + +### Project Structure +``` +src/ +├── Purview.Telemetry.SourceGenerator/ # Main source generator library +├── Purview.Telemetry.SourceGenerator.IntegrationTests/ # 282 integration tests +├── Purview.Telemetry.SourceGenerator.slnx # Main solution +└── global.json # Pins to .NET 9.0.200 + +samples/ +└── SampleApp/ # .NET Aspire demo application + ├── SampleApp.AppHost/ # Aspire AppHost + ├── SampleApp.Host/ # Main web API + ├── SampleApp.ServiceDefaults/ # Shared service config + ├── SampleApp.UnitTests/ # Sample app tests + └── SampleApp.slnx # Sample solution + +.build/ +├── common.mk # Shared Makefile targets +└── update-version.ts # Version management script + +Makefile # Main build automation +package.json # Version 3.2.4, Bun scripts +``` + +### Key Commands Output + +#### make help +``` +build Builds the project. +test Runs the tests for the project. +release-final Creates a new release, e.g. v3.0.1. +release-pre Creates a new pre-release, e.g. v3.0.1-prerelease.1. +pack Packs the project into a nuget package using PACK_VERSION argument. +format Formats the code according to the rules of the src/.editorconfig file. +vs Opens the project in Visual Studio. +code Opens the project in Visual Studio Code. +vs-s Opens the sample project in Visual Studio. +version Displays the current version of the project. +update-version Update related samples and docs to new version. +``` + +#### Repository Root Files +``` +.build/ .config/ .cspell.json .git/ +.gitattributes .github/ .gitignore .gitmodules +.husky/ .vscode/ .wiki/ CHANGELOG.md +LICENSE.md Makefile README.md bun.lock +global.json package.json samples/ src/ +``` + +### Source Generator Architecture +The source generator processes interface definitions and generates three types of telemetry code: +- **Activities**: Distributed tracing using ActivitySource +- **Logging**: Structured logging using ILogger +- **Metrics**: Performance metrics using .NET metrics APIs + +Generated code includes: +- Implementation classes with telemetry instrumentation +- Dependency injection registration helpers +- Configuration and initialization code + +### Generated Code Location +When `EmitCompilerGeneratedFiles` is true (as in the sample app), generated files appear in: +- `obj/Debug|Release/generated/` directories +- Integration test snapshots in `src/Purview.Telemetry.SourceGenerator.IntegrationTests/Snapshots/` + +### Version Management +- Version is managed in `package.json` (currently 3.2.4) +- `bun .build/update-version.js` synchronizes version across all files +- `make release-final` and `make release-pre` create new releases using commit-and-tag-version + +## CRITICAL Timing and Cancellation Warnings +- **NEVER CANCEL** any build or test command - builds may take up to 60 minutes in some environments +- **Build timeout**: Set 60+ minutes timeout for `make build` and related commands +- **Test timeout**: Set 60+ minutes timeout for `make test` and related commands +- **Format timeout**: Set 30+ minutes timeout for `make format` +- **Expected times**: Build ~26s, Test ~42s, Format ~21s, Sample build ~19s on typical hardware + +## Important Development Notes +- The project uses .slnx solution files (Visual Studio 2022 format) +- Source generator targets netstandard2.0 for broad compatibility +- Integration tests target net9.0 +- Sample application is a .NET Aspire application demonstrating telemetry integration +- Always test changes against the sample application to ensure end-to-end functionality +- The integration tests use Verify for snapshot testing of generated code \ No newline at end of file From 8cfbee68a3b0993b0b1629fbc7dc6859ec9bea0c Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Sat, 30 Aug 2025 15:29:32 +0100 Subject: [PATCH 3/5] docs: added copilot instructions Updated the Purview Telemetry Source Generator documentation to clarify it is an incremental source generator and added detailed instructions for building, testing, and validation. --- .github/copilot-instructions.md | 28 ++++++++++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 84978606..92c9cda5 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,49 +1,61 @@ # Purview Telemetry Source Generator -Purview Telemetry Source Generator is a .NET 9.0 source generator that generates [`ActivitySource`](https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.activitysource), [`ILogger`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.logging.ilogger), and [`Metrics`](https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.metrics) based telemetry from methods you define on an interface. +Purview Telemetry Source Generator is a .NET incremental source generator that generates [`ActivitySource`](https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.activitysource), [`ILogger`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.logging.ilogger), and [`Metrics`](https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.metrics) based telemetry from methods you define on an interface. Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here. ## Working Effectively ### Prerequisites + Install these exact dependencies in order: + - Install .NET 9.0.200 SDK: `curl -sSL https://dot.net/v1/dotnet-install.sh | bash -s -- --version 9.0.200` - Install .NET 9.0 runtime: `curl -sSL https://dot.net/v1/dotnet-install.sh | bash -s -- --runtime dotnet --version 9.0.0` - Install Bun: `curl -fsSL https://bun.sh/install | bash` - Set environment variables: `export PATH=$HOME/.bun/bin:$HOME/.dotnet:$PATH && export DOTNET_ROOT=$HOME/.dotnet` ### Bootstrap, Build, and Test + Bootstrap and build the repository: + - `make build` -- builds the main source generator and integration tests. Takes 26 seconds. NEVER CANCEL. Set timeout to 60+ minutes. - `make test` -- runs 282 integration tests. Takes 42 seconds. NEVER CANCEL. Set timeout to 60+ minutes. - `make format` -- formats code according to .editorconfig rules. Takes 21 seconds. NEVER CANCEL. Set timeout to 30+ minutes. Alternative direct commands (use environment variables above): + - `dotnet build ./src/Purview.Telemetry.SourceGenerator.slnx --configuration Release` - `dotnet test ./src/Purview.Telemetry.SourceGenerator.slnx --configuration Release` - `dotnet format ./src/` ### Build and Test Sample Application + The sample application demonstrates the source generator in action: + - `cd samples/SampleApp && dotnet build --configuration Release` -- takes 19 seconds. NEVER CANCEL. Set timeout to 30+ minutes. - `cd samples/SampleApp && dotnet test --configuration Release` -- runs 8 tests, takes 3 seconds. ### Package Creation + - `make pack` -- creates NuGet package with current version from package.json - `make version` -- displays current version (currently 3.2.4) ## Validation ### Manual Validation Requirements + Always manually validate changes to the source generator: + - ALWAYS run `make build && make test` after making any changes to the source generator code - ALWAYS build and test the sample application: `cd samples/SampleApp && dotnet build --configuration Release && dotnet test --configuration Release` - ALWAYS run `make format` before committing to ensure code formatting compliance - Test actual source generator functionality by examining generated files in the sample project (EmitCompilerGeneratedFiles is enabled) ### Functional Testing Scenarios + Test these scenarios when modifying the source generator: + - **Interface to Implementation Generation**: Modify an interface in `samples/SampleApp/SampleApp.Host/APIs/` and verify generated telemetry code appears - **Activity Generation**: Test ActivitySource generation by adding methods with activity attributes - **Logging Generation**: Test ILogger generation by adding methods with logging attributes @@ -51,7 +63,9 @@ Test these scenarios when modifying the source generator: - **Integration Test Coverage**: Verify new functionality is covered by tests in `src/Purview.Telemetry.SourceGenerator.IntegrationTests/` ### CI Validation + Always run these validation steps before committing: + - `make format` (takes 21 seconds) - `make build` (takes 26 seconds) - `make test` (takes 42 seconds) @@ -112,27 +126,35 @@ global.json package.json samples/ src/ ``` ### Source Generator Architecture + The source generator processes interface definitions and generates three types of telemetry code: + - **Activities**: Distributed tracing using ActivitySource - **Logging**: Structured logging using ILogger - **Metrics**: Performance metrics using .NET metrics APIs Generated code includes: + - Implementation classes with telemetry instrumentation - Dependency injection registration helpers - Configuration and initialization code ### Generated Code Location + When `EmitCompilerGeneratedFiles` is true (as in the sample app), generated files appear in: + - `obj/Debug|Release/generated/` directories - Integration test snapshots in `src/Purview.Telemetry.SourceGenerator.IntegrationTests/Snapshots/` ### Version Management + - Version is managed in `package.json` (currently 3.2.4) + - `bun .build/update-version.js` synchronizes version across all files - `make release-final` and `make release-pre` create new releases using commit-and-tag-version ## CRITICAL Timing and Cancellation Warnings + - **NEVER CANCEL** any build or test command - builds may take up to 60 minutes in some environments - **Build timeout**: Set 60+ minutes timeout for `make build` and related commands - **Test timeout**: Set 60+ minutes timeout for `make test` and related commands @@ -140,9 +162,11 @@ When `EmitCompilerGeneratedFiles` is true (as in the sample app), generated file - **Expected times**: Build ~26s, Test ~42s, Format ~21s, Sample build ~19s on typical hardware ## Important Development Notes + +- Always use conventional commits - The project uses .slnx solution files (Visual Studio 2022 format) - Source generator targets netstandard2.0 for broad compatibility - Integration tests target net9.0 - Sample application is a .NET Aspire application demonstrating telemetry integration - Always test changes against the sample application to ensure end-to-end functionality -- The integration tests use Verify for snapshot testing of generated code \ No newline at end of file +- The integration tests use Verify for snapshot testing of generated code From bfc767f5ea14b2438ef1da71e9ac9306ee54304e Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Sat, 30 Aug 2025 15:31:24 +0100 Subject: [PATCH 4/5] docs: js -> ts Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 92c9cda5..5f6d9eb4 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -150,7 +150,7 @@ When `EmitCompilerGeneratedFiles` is true (as in the sample app), generated file - Version is managed in `package.json` (currently 3.2.4) -- `bun .build/update-version.js` synchronizes version across all files +- `bun .build/update-version.ts` synchronizes version across all files - `make release-final` and `make release-pre` create new releases using commit-and-tag-version ## CRITICAL Timing and Cancellation Warnings From 71713edf9410713bf90b05b5e7328cc2715c716e Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Sat, 30 Aug 2025 15:31:36 +0100 Subject: [PATCH 5/5] docs: fix github dir Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 5f6d9eb4..c407b5c3 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -71,7 +71,7 @@ Always run these validation steps before committing: - `make test` (takes 42 seconds) - Sample app build and test (takes 22 seconds total) -The CI pipeline (`./github/workflows/ci.yml`) runs the same dotnet restore → build → test workflow. +The CI pipeline (`./.github/workflows/ci.yml`) runs the same dotnet restore → build → test workflow. ## Common Tasks