From c659fd7922f1bba9135b6f9a0cecd35abd608d90 Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Tue, 29 Sep 2026 12:59:28 +0100 Subject: [PATCH] docs(release): updated shipped/ release docs --- .../prompts/sdk-diagnose-agent-folder-copy.md | 21 +++- AGENTS.md | 10 +- README.md | 15 ++- docs/release-process.md | 15 ++- docs/wiki/Diagnostics.md | 107 +++++++++--------- docs/wiki/Generated-Output.md | 2 +- docs/wiki/Release-Flow.md | 2 +- global.json | 2 +- package.json | 2 +- samples/SampleApp/README.md | 4 +- .../AnalyzerReleases.Shipped.md | 61 ++++++++++ .../AnalyzerReleases.Unshipped.md | 7 ++ .../SourceGenerator/SourceGenerator.csproj | 16 ++- ...lemetrySourceGeneratorTests.Docs_README.cs | 8 +- 14 files changed, 194 insertions(+), 78 deletions(-) create mode 100644 src/src/SourceGenerator/AnalyzerReleases.Shipped.md create mode 100644 src/src/SourceGenerator/AnalyzerReleases.Unshipped.md diff --git a/.agents/prompts/sdk-diagnose-agent-folder-copy.md b/.agents/prompts/sdk-diagnose-agent-folder-copy.md index 85ad4445..e234df90 100644 --- a/.agents/prompts/sdk-diagnose-agent-folder-copy.md +++ b/.agents/prompts/sdk-diagnose-agent-folder-copy.md @@ -11,16 +11,27 @@ destination in a consuming repository. 3. Check `EnableAgentFolderInPackage` is not set to `false` anywhere in the build (project file, `Directory.Build.props`, or command-line `-p:` overrides). 4. Confirm the destination folder: default is `.agents` at the repo root, overridable per-build with - `-p:AgentPackDestinationFolder=`. + `-p:AgentPackDestinationFolder=`, and the source defaults to the package-level `.agents` + folder (override with `PurviewAgentFolderSourcePath`). 5. Verify repo-root discovery succeeded: explicit `RepoRoot`, then a nearby `AGENTS.md`, then source-control root metadata. -6. Re-run the build and confirm the destination folder now contains the copied files (including the +6. If the destination looks stale or incomplete, inspect the change-detection manifest + (`/.purview/agent-sync.cache`). It lists the files the SDK believes it already mirrored; a + matching entry with a present destination file means the sync was skipped as up to date. Delete the + manifest (or the affected destination file) to force a fresh copy. +7. Retry notices are demoted to low-importance messages, so a healthy build shows no `MSB3026` warnings. + A copy that still fails after every retry is reported as an error naming the source, destination and + OS error - search the build log for `The Purview SDK could not copy`. Temporarily set + `PurviewAgentFolderCopyRetries` / `PurviewAgentFolderCopyRetryDelayMilliseconds` to retry longer, and + `PurviewSuppressCopyRetryWarnings=false` to see every retry attempt. +8. Re-run the build and confirm the destination folder now contains the copied files (including the generated `.gitignore` for skill/prompt/agent subfolders). ## Suggested output -- A short root-cause explanation (missing import, disabled flag, wrong destination override, or repo-root - discovery miss). +- A short root-cause explanation (missing import, disabled flag, wrong destination override, repo-root + discovery miss, or a destination held open by another process). - The exact command used to reproduce/verify the fix (for example `dotnet build -p:AgentPackDestinationFolder=`). -- Confirmation that the expected files exist at the resolved destination path. +- Confirmation that the expected files exist at the resolved destination path, plus whether the + manifest skipped the sync (in which case the content was already up to date). diff --git a/AGENTS.md b/AGENTS.md index 0d66524c..3ecc8185 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -62,7 +62,7 @@ conventional-commits check. | `just update-version` | Runs `.build/update-version.ts` to sync the version into docs/samples. | | `just pack` | Updates the version then packs the NuGet package into `artifacts/`. | -The version lives in `package.json`. **Current Version:** 5.0.0-prerelease.13 — applied to `Version` / +The version lives in `package.json`. **Current Version:** 5.0.0 — applied to `Version` / `PackageVersion` via the SDK's package.json version detection. ### Pipelines (reusable `purview-build` tool) @@ -100,6 +100,8 @@ src/ ├── src/ │ ├── SourceGenerator/ # Main incremental source generator (netstandard2.0, Roslyn) │ │ ├── Analyzers/ # Diagnostic analyzers for telemetry interfaces +│ │ ├── AnalyzerReleases.Shipped.md # Roslyn analyzer release tracking (shipped TSG rules) +│ │ ├── AnalyzerReleases.Unshipped.md # Roslyn analyzer release tracking (upcoming TSG rules) │ │ ├── Emitters/ # CodeWriter-based code emission │ │ ├── Generators/ # Incremental generator pipeline │ │ └── Sdk/ # SDK-style package content (props/targets) @@ -158,6 +160,12 @@ The sample projects enable `EmitCompilerGeneratedFiles`, so generated telemetry - **SDK**: projects import `Purview.BuildSdk` via `Directory.Build.props`/`.targets`. The repo sets `ExcludePurviewTelemetry=true` (it does not consume the telemetry package it generates) and `NamespacePrefix=Purview.Telemetry` under `src/`. See `.agents/skills/sdk-*` for SDK behavior. +- **Analyzer release tracking**: the `TSG` rules are tracked in + `src/src/SourceGenerator/AnalyzerReleases.{Shipped,Unshipped}.md` (wired as `AdditionalFiles`, so + the Roslyn RS2000-series checks run under `EnforceExtendedAnalyzerRules=true`). Add new rules to + `AnalyzerReleases.Unshipped.md`, then move them into a new `## Release x.y.z` section in + `AnalyzerReleases.Shipped.md` at release time. `RS2003` is suppressed — see the comment in + `src/src/SourceGenerator/SourceGenerator.csproj`. ## Source-generator and testing skills diff --git a/README.md b/README.md index f58f269d..4e69705e 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ Generates [`ActivitySource`](https://learn.microsoft.com/en-us/dotnet/api/system Add to your `Directory.Build.props` or `.csproj` file: ```xml - + all analyzers @@ -132,16 +132,15 @@ public class EntityService(IEntityStoreTelemetry telemetry) | `[ObservableCounter]`, `[ObservableGauge]`, `[ObservableUpDownCounter]` | Method | Observable instruments | > [!TIP] -> For single-target interfaces (only Activities, only Logging, or only Metrics), the generator automatically infers the necessary attributes. See the [wiki](https://github.com/purview-dev/telemetry-sourcegenerator/wiki/Multi-Targeting) for details. +> For single-target interfaces (only Activities, only Logging, or only Metrics), the generator automatically infers the necessary attributes. See the [Multi-Targeting guide](https://purview.dev/docs/telemetry-sourcegenerator/multi-targeting/) for details. ## Documentation - [Homepage](https://purview.dev/projects/telemetry-sourcegenerator/) - [Documentation](https://purview.dev/docs/telemetry-sourcegenerator/) -- [Full Wiki](https://github.com/purview-dev/telemetry-sourcegenerator/wiki) -- [Generated Output Examples](https://github.com/purview-dev/telemetry-sourcegenerator/wiki/Generated-Output) -- [Multi-Targeting Guide](https://github.com/purview-dev/telemetry-sourcegenerator/wiki/Multi-Targeting) -- [Logging Configuration](https://github.com/purview-dev/telemetry-sourcegenerator/wiki/Logging) +- [Generated Output Examples](https://purview.dev/docs/telemetry-sourcegenerator/generated-output/) +- [Multi-Targeting Guide](https://purview.dev/docs/telemetry-sourcegenerator/multi-targeting/) +- [Logging Configuration](https://purview.dev/docs/telemetry-sourcegenerator/logging/) ## Agent Skills @@ -156,7 +155,7 @@ The [.NET Aspire Sample](https://github.com/purview-dev/telemetry-sourcegenerato ## Performance -Benchmarked on 13th Gen Intel Core i9-13900KF, .NET SDK 10.0.401. See the [Performance](https://github.com/purview-dev/telemetry-sourcegenerator/wiki/Performance) wiki page for full cross-runtime results. +Benchmarked on 13th Gen Intel Core i9-13900KF, .NET SDK 10.0.401. See the [Performance](https://purview.dev/docs/telemetry-sourcegenerator/performance/) page for full cross-runtime results. ### Activities (.NET 10.0) @@ -290,7 +289,7 @@ public enum NamingConvention ## Contributing -Contributions are welcome! See the [Contributing guide](https://github.com/purview-dev/telemetry-sourcegenerator/wiki/Contributing) for development setup and testing instructions. +Contributions are welcome! See the [Contributing guide](https://purview.dev/docs/telemetry-sourcegenerator/contributing/) for development setup and testing instructions. See [docs/release-process.md](docs/release-process.md) for the release flow, and [`AGENTS.md`](AGENTS.md) for the build, validation, and convention rules. Bump the version in `package.json` and run diff --git a/docs/release-process.md b/docs/release-process.md index cd16d4b7..8265bd87 100644 --- a/docs/release-process.md +++ b/docs/release-process.md @@ -70,12 +70,25 @@ Merging to `main` triggers `release.yml`, which runs the reusable `purview-relea ## Versioning -- The version lives in `package.json`. **Current Version:** 5.0.0-prerelease.13 +- The version lives in `package.json`. **Current Version:** 5.0.0 - It is applied to `Version` / `PackageVersion` by `Purview.BuildSdk` via package.json version detection (`UsePackageJsonVersion`, default `true`). - `just version` prints the current version. - After bumping `package.json`, run `just update-version` to sync the version into docs/samples. +### Analyzer release tracking + +The `TSG` diagnostics are tracked in `src/src/SourceGenerator/AnalyzerReleases.Shipped.md` and +`src/src/SourceGenerator/AnalyzerReleases.Unshipped.md`. The files are wired up as `AdditionalFiles`, +so the Roslyn release-tracking analyzers validate them on every build (`EnforceExtendedAnalyzerRules` +is enabled by `Purview.BuildSdk`). + +1. Add new rules to `AnalyzerReleases.Unshipped.md`. +2. At release time, create a new `## Release ` section in `AnalyzerReleases.Shipped.md`, + move the unshipped entries into it, and leave the unshipped file empty. +3. Keep the rule ID, category, and severity in sync with the `DiagnosticDescriptor`s in + `src/src/SourceGenerator/Helpers/DiagnosticLibrary.*.cs`. + ## Building the package locally | Command | Purpose | diff --git a/docs/wiki/Diagnostics.md b/docs/wiki/Diagnostics.md index 254dc87d..3e4e92f4 100644 --- a/docs/wiki/Diagnostics.md +++ b/docs/wiki/Diagnostics.md @@ -2,6 +2,11 @@ The package ships a single Roslyn analyzer, `TelemetryDiagnosticAnalyzer`, which validates telemetry interfaces and raises diagnostics with the `TSG` prefix. All diagnostics are grouped by category. +> [!NOTE] +> Each rule is also tracked for release purposes in `AnalyzerReleases.Shipped.md` and +> `AnalyzerReleases.Unshipped.md`, which carry the rule ID, category, and severity and are validated by +> the Roslyn release-tracking analyzers on every build. + - **General** — `TSG1xxx` - **Logging** — `TSG2xxx` - **Activities** — `TSG3xxx` @@ -11,72 +16,72 @@ The package ships a single Roslyn analyzer, `TelemetryDiagnosticAnalyzer`, which | ID | Severity | Description | | --- | --- | --- | -| `TSG1000` | Error | Fatal execution error occurred (`Failed to execute the generation stage: {0}`). Raised by the generator itself when an unexpected exception escapes the pipeline. | -| `TSG1001` | Error | Inferring generation targets is not supported when using multi-target generation. A method on a multi-target interface has no explicit generation attribute. | -| `TSG1002` | Error | Multiple attributes from the same target family are not supported. Only one Activity, Logging, or Metrics attribute is allowed per method. | -| `TSG1003` | Error | Duplicate method names are not supported. Two or more methods on the interface share the same name. | -| `TSG1004` | Error | Generic interfaces are not supported. | -| `TSG1005` | Error | Generic methods are not supported. | -| `TSG1006` | Warning | `ExcludeTargets` references a target not present on this method. | -| `TSG1007` | Warning | `ExcludeTargets` results in an empty or invalid parameter set for a target. | -| `TSG1008` | Warning | Activity parameter has no Activity target. A parameter of type `Activity` is present on a method with no `[Activity]`/`[Event]`/`[Context]` attribute. | -| `TSG1010` | Error | Method target not registered on interface. A method carries an attribute for a target family that is not registered on the interface. | -| `TSG1011` | Error | Unsupported target framework. The compilation targets neither .NET 8+ nor .NET Framework 4.8+; define `PURVIEW_TELEMETRY_NON_NULLABLE` to opt out. | +| `TSG1000` | Error | Fatal execution error occurred (`Failed to execute the generation stage: {0}`). Raised by the generator itself when an unexpected exception escapes the pipeline. | +| `TSG1001` | Error | Inferring generation targets is not supported when using multi-target generation. A method on a multi-target interface has no explicit generation attribute. | +| `TSG1002` | Error | Multiple attributes from the same target family are not supported. Only one Activity, Logging, or Metrics attribute is allowed per method. | +| `TSG1003` | Error | Duplicate method names are not supported. Two or more methods on the interface share the same name. | +| `TSG1004` | Error | Generic interfaces are not supported. | +| `TSG1005` | Error | Generic methods are not supported. | +| `TSG1006` | Warning | `ExcludeTargets` references a target not present on this method. | +| `TSG1007` | Warning | `ExcludeTargets` results in an empty or invalid parameter set for a target. | +| `TSG1008` | Warning | Activity parameter has no Activity target. A parameter of type `Activity` is present on a method with no `[Activity]`/`[Event]`/`[Context]` attribute. | +| `TSG1010` | Error | Method target not registered on interface. A method carries an attribute for a target family that is not registered on the interface. | +| `TSG1011` | Error | Unsupported target framework. The compilation targets neither .NET 8+ nor .NET Framework 4.8+; define `PURVIEW_TELEMETRY_NON_NULLABLE` to opt out. | ## Logging diagnostics (TSG2xxx) | ID | Severity | Description | | --- | --- | --- | -| `TSG2000` | Error | Too many exception parameters. A non-scoped log method has more than one `Exception`-typed parameter. | -| `TSG2001` | Error | More than 6 parameters. A log method in v1 generation mode has more than 6 non-exception parameters. | -| `TSG2002` | Info | Inferring error log level. In v1 generation, a single `Exception` parameter is present with no explicit level, so `Error` is inferred. | -| `TSG2003` | Warning | Could not find a reference to `Microsoft.Extensions.Logging.ILogger`, skipping log generation. | -| `TSG2004` | Error | Cannot mix ordinal and named property placeholders in a message template. | -| `TSG2005` | Error | Ordinal values exceed parameter count. The maximum ordinal placeholder value exceeds the number of provided parameters. | -| `TSG2006` | Error | Using `[LogProperties]` and `[ExpandEnumerable]` on the same parameter is not supported. | -| `TSG2007` | Warning | A scoped log shouldn't have a `LogLevel`; it will be ignored. | -| `TSG2008` | Warning | Unbounded enumeration possible. `[ExpandEnumerable]` has a `MaximumValueCount` greater than the recommended default of 5. | -| `TSG2021` | Error | Log method must return void or IDisposable. (Returning `Activity` is allowed when the method is also an Activity method.) | +| `TSG2000` | Error | Too many exception parameters. A non-scoped log method has more than one `Exception`-typed parameter. | +| `TSG2001` | Error | More than 6 parameters. A log method in v1 generation mode has more than 6 non-exception parameters. | +| `TSG2002` | Info | Inferring error log level. In v1 generation, a single `Exception` parameter is present with no explicit level, so `Error` is inferred. | +| `TSG2003` | Warning | Could not find a reference to `Microsoft.Extensions.Logging.ILogger`, skipping log generation. | +| `TSG2004` | Error | Cannot mix ordinal and named property placeholders in a message template. | +| `TSG2005` | Error | Ordinal values exceed parameter count. The maximum ordinal placeholder value exceeds the number of provided parameters. | +| `TSG2006` | Error | Using `[LogProperties]` and `[ExpandEnumerable]` on the same parameter is not supported. | +| `TSG2007` | Warning | A scoped log shouldn't have a `LogLevel`; it will be ignored. | +| `TSG2008` | Warning | Unbounded enumeration possible. `[ExpandEnumerable]` has a `MaximumValueCount` greater than the recommended default of 5. | +| `TSG2021` | Error | Log method must return void or IDisposable. (Returning `Activity` is allowed when the method is also an Activity method.) | ## Activities diagnostics (TSG3xxx) | ID | Severity | Description | | --- | --- | --- | -| `TSG3000` | Warning | Baggage parameter types only accept strings (`ToString()` will be called). | -| `TSG3001` | Warning | No activity source specified. Generation defaults to `purview` when no name is available anywhere. | -| `TSG3002` | Error | Invalid return type. An Activity/Event method returns something other than `void` or `System.Diagnostics.Activity`. | -| `TSG3003` | Error | Duplicate reserved parameters defined. More than one parameter maps to the same reserved destination. | -| `TSG3004` | Error | Activity parameter is not valid. An `Activity`-destination parameter appears on an Activity method (only valid on `[Event]` methods). | -| `TSG3005` | Error | Timestamp parameter is not valid. A `timestamp` parameter appears on a method that is not an `[Event]` method. | -| `TSG3006` | Error | Start time parameter is not valid on Create activity or Event method. | -| `TSG3007` | Error | Parent context or Parent Id parameter is not valid on event. | -| `TSG3008` | Error | Activity links parameters are not valid on events or context methods. | -| `TSG3009` | Error | Activity tags parameter is not valid on context methods. | -| `TSG3010` | Error | Escaped parameters must be a boolean. | -| `TSG3011` | Error | Escaped parameters are only valid on Events, not Activity or Context methods. | -| `TSG3012` | Info | There are no Activity methods defined, assumed use of `Activity.Current`. | -| `TSG3013` | Warning | Should return the created Activity. An Activity method does not return the created `Activity`. | -| `TSG3014` | Warning | Should accept an Activity to apply the Event/Tags/Baggage to. An Event/Context method has no `Activity` parameter. Opt-in via `ActivitySourceGeneration.GenerateDiagnosticsForMissingActivity` (default `true`). | -| `TSG3015` | Info | Activity should be the first parameter. Opt-in via `GenerateDiagnosticsForMissingActivity`. | -| `TSG3016` | Error | Status description parameter should be a string. | -| `TSG3017` | Error | Status Description parameters are only valid on Events, not Activity or Context methods. | -| `TSG3021` | Info | Exception event does not use OpenTelemetry standard name. An `[Event]` method records an exception under the OpenTelemetry exception rules but the event name is not the standard `"exception"` (suggest `[Event(Name = "exception")]`). Not raised when `UseRecordExceptionRules` is disabled, for `[Baggage]` exceptions, or when the exception parameter is excluded from the Activities target. | -| `TSG3022` | Warning | Activity return type should be nullable. An Activity method returns non-nullable `Activity`; use `Activity?` because the Activity can be null when no listeners are active. | +| `TSG3000` | Warning | Baggage parameter types only accept strings (`ToString()` will be called). | +| `TSG3001` | Warning | No activity source specified. Generation defaults to `purview` when no name is available anywhere. | +| `TSG3002` | Error | Invalid return type. An Activity/Event method returns something other than `void` or `System.Diagnostics.Activity`. | +| `TSG3003` | Error | Duplicate reserved parameters defined. More than one parameter maps to the same reserved destination. | +| `TSG3004` | Error | Activity parameter is not valid. An `Activity`-destination parameter appears on an Activity method (only valid on `[Event]` methods). | +| `TSG3005` | Error | Timestamp parameter is not valid. A `timestamp` parameter appears on a method that is not an `[Event]` method. | +| `TSG3006` | Error | Start time parameter is not valid on Create activity or Event method. | +| `TSG3007` | Error | Parent context or Parent Id parameter is not valid on event. | +| `TSG3008` | Error | Activity links parameters are not valid on events or context methods. | +| `TSG3009` | Error | Activity tags parameter is not valid on context methods. | +| `TSG3010` | Error | Escaped parameters must be a boolean. | +| `TSG3011` | Error | Escaped parameters are only valid on Events, not Activity or Context methods. | +| `TSG3012` | Info | There are no Activity methods defined, assumed use of `Activity.Current`. | +| `TSG3013` | Warning | Should return the created Activity. An Activity method does not return the created `Activity`. | +| `TSG3014` | Warning | Should accept an Activity to apply the Event/Tags/Baggage to. An Event/Context method has no `Activity` parameter. Opt-in via `ActivitySourceGeneration.GenerateDiagnosticsForMissingActivity` (default `true`). | +| `TSG3015` | Info | Activity should be the first parameter. Opt-in via `GenerateDiagnosticsForMissingActivity`. | +| `TSG3016` | Error | Status description parameter should be a string. | +| `TSG3017` | Error | Status Description parameters are only valid on Events, not Activity or Context methods. | +| `TSG3021` | Info | Exception event does not use OpenTelemetry standard name. An `[Event]` method records an exception under the OpenTelemetry exception rules but the event name is not the standard `"exception"` (suggest `[Event(Name = "exception")]`). Not raised when `UseRecordExceptionRules` is disabled, for `[Baggage]` exceptions, or when the exception parameter is excluded from the Activities target. | +| `TSG3022` | Warning | Activity return type should be nullable. An Activity method returns non-nullable `Activity`; use `Activity?` because the Activity can be null when no listeners are active. | ## Metrics diagnostics (TSG4xxx) | ID | Severity | Description | | --- | --- | --- | -| `TSG4000` | Error | No instrument defined. A method on a Metrics interface has no instrument attribute and is not excluded. | -| `TSG4001` | Error | Must return void or bool. A metrics-owned method returns something other than `void` or `bool`. | -| `TSG4002` | Error | Auto increment counter and measurement defined. An auto-increment instrument also has a measurement parameter. | -| `TSG4003` | Error | Multiple measurement values defined. | -| `TSG4004` | Error | No measurement value defined. A non-auto-increment instrument method has no measurement parameter. | -| `TSG4005` | Error | Observable instrument requires `Func`. | -| `TSG4006` | Error | Invalid measurement type. Not one of `byte`, `short`, `int`, `long`, `double`, `float`, `decimal`, `Measurement`, or `IEnumerable>`. | -| `TSG4007` | Error | Observable metrics cannot return bool. | -| `TSG4008` | Error | AutoCounter must return void. | -| `TSG4009` | Warning | Instrument name matches the instrument type name. Use a name that describes what is measured. | +| `TSG4000` | Error | No instrument defined. A method on a Metrics interface has no instrument attribute and is not excluded. | +| `TSG4001` | Error | Must return void or bool. A metrics-owned method returns something other than `void` or `bool`. | +| `TSG4002` | Error | Auto increment counter and measurement defined. An auto-increment instrument also has a measurement parameter. | +| `TSG4003` | Error | Multiple measurement values defined. | +| `TSG4004` | Error | No measurement value defined. A non-auto-increment instrument method has no measurement parameter. | +| `TSG4005` | Error | Observable instrument requires `Func`. | +| `TSG4006` | Error | Invalid measurement type. Not one of `byte`, `short`, `int`, `long`, `double`, `float`, `decimal`, `Measurement`, or `IEnumerable>`. | +| `TSG4007` | Error | Observable metrics cannot return bool. | +| `TSG4008` | Error | AutoCounter must return void. | +| `TSG4009` | Warning | Instrument name matches the instrument type name. Use a name that describes what is measured. | ## Common resolutions diff --git a/docs/wiki/Generated-Output.md b/docs/wiki/Generated-Output.md index 4e886b21..4dfe448f 100644 --- a/docs/wiki/Generated-Output.md +++ b/docs/wiki/Generated-Output.md @@ -1,6 +1,6 @@ # Generated Output -This page shows real generated output from the [sample application](Sample-Application.md), produced by `5.0.0-prerelease.8`. The interface: +This page shows real generated output from the [sample application](Sample-Application.md), produced by `5.0.0`. The interface: ```csharp [ActivitySource] diff --git a/docs/wiki/Release-Flow.md b/docs/wiki/Release-Flow.md index 11d968f3..98289bd1 100644 --- a/docs/wiki/Release-Flow.md +++ b/docs/wiki/Release-Flow.md @@ -27,7 +27,7 @@ Feature branch ## Versioning -- The version lives in `package.json`. **Current Version:** 5.0.0-prerelease.8 +- The version lives in `package.json`. **Current Version:** 5.0.0 - It is applied to `Version`/`PackageVersion` by `Purview.BuildSdk` via package.json version detection. - `just version` prints the current version. - After bumping `package.json`, run `just update-version` to sync the version into docs/samples. diff --git a/global.json b/global.json index 0961f097..7f367b18 100644 --- a/global.json +++ b/global.json @@ -3,7 +3,7 @@ "allowPrerelease": false }, "msbuild-sdks": { - "Purview.BuildSdk": "1.0.0-prerelease.60" + "Purview.BuildSdk": "1.0.0" }, "test": { "runner": "Microsoft.Testing.Platform" diff --git a/package.json b/package.json index ca24d47d..f9095d67 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "purview-telemetry-sourcegenerator", - "version": "5.0.0-prerelease.19", + "version": "5.0.0", "description": "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 on interface methods.", "license": "MIT", "readme": "README.md", diff --git a/samples/SampleApp/README.md b/samples/SampleApp/README.md index 23007ead..32acc6e3 100644 --- a/samples/SampleApp/README.md +++ b/samples/SampleApp/README.md @@ -284,7 +284,7 @@ dotnet-counters monitor --process-id --counters SampleApp.APIService.Servi ## Learn More - [Purview Telemetry Source Generator docs](../../README.md) -- [Wiki: Sample Application](https://github.com/purview-dev/telemetry-sourcegenerator/wiki/Sample-Application) — annotated walkthroughs, sequence diagrams, dashboard screenshots -- [Wiki: Generated Output](https://github.com/purview-dev/telemetry-sourcegenerator/wiki/Generated-Output) — full annotated examples of generated code +- [Sample Application](https://purview.dev/docs/telemetry-sourcegenerator/sample-application/) — annotated walkthroughs, sequence diagrams, dashboard screenshots +- [Generated Output](https://purview.dev/docs/telemetry-sourcegenerator/generated-output/) — full annotated examples of generated code - [.NET Aspire](https://learn.microsoft.com/en-us/dotnet/aspire/) diff --git a/src/src/SourceGenerator/AnalyzerReleases.Shipped.md b/src/src/SourceGenerator/AnalyzerReleases.Shipped.md new file mode 100644 index 00000000..1f0428e0 --- /dev/null +++ b/src/src/SourceGenerator/AnalyzerReleases.Shipped.md @@ -0,0 +1,61 @@ +; Shipped analyzer releases +; Release list format: release with release version followed by analyzer rules in a table. + +## Release 5.0.0 + +### New Rules + +Rule ID | Category | Severity | Notes +--------|----------|----------|------- +TSG1000 | Usage | Error | [Fatal execution error occurred](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg1000) +TSG1001 | Usage | Error | [Inferring generation targets is not supported when using multi-target generation](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg1001) +TSG1002 | Usage | Error | [Multiple attributes from the same target family are not supported](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg1002) +TSG1003 | Usage | Error | [Duplicate method names are not supported](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg1003) +TSG1004 | Usage | Error | [Generic interfaces are not supported](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg1004) +TSG1005 | Usage | Error | [Generic methods are not supported](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg1005) +TSG1006 | Usage | Warning | [ExcludeTargets references a target not present on this method](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg1006) +TSG1007 | Usage | Warning | [ExcludeTargets results in an empty or invalid parameter set for a target](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg1007) +TSG1008 | Usage | Warning | [Activity parameter has no Activity target](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg1008) +TSG1010 | Usage | Error | [Method target not registered on interface](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg1010) +TSG1011 | Usage | Error | [Unsupported target framework](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg1011) +TSG2000 | Logging.Usage | Error | [Too many exception parameters](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg2000) +TSG2001 | Logging.Usage | Error | [More than 6 parameters](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg2001) +TSG2002 | Logging.Usage | Info | [Inferring error log level](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg2002) +TSG2003 | Logging.Usage | Warning | [Could not find a reference to Microsoft.Extensions.Logging.ILogger, skipping log generation](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg2003) +TSG2004 | Logging.Usage | Error | [Cannot mix ordinal and named property placeholders](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg2004) +TSG2005 | Logging.Usage | Error | [Ordinal values exceed parameter count](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg2005) +TSG2006 | Logging.Usage | Error | [Using LogPropertiesAttribute and ExpandEnumerableAttribute on the same parameter is not supported](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg2006) +TSG2007 | Logging.Usage | Warning | [A scoped log shouldn't have a LogLevel, this will be ignored](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg2007) +TSG2008 | Logging.Performance | Warning | [Unbounded enumeration possible](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg2008) +TSG2021 | Logging.Usage | Error | [Log method must return void or IDisposable](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg2021) +TSG3000 | Activity.Usage | Warning | [Baggage parameter types only accept strings](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg3000) +TSG3001 | Activity.Usage | Warning | [No activity source specified](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg3001) +TSG3002 | Activity.Usage | Error | [Invalid return type](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg3002) +TSG3003 | Activity.Usage | Error | [Duplicate reserved parameters defined](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg3003) +TSG3004 | Activity.Usage | Error | [Activity parameter is not valid](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg3004) +TSG3005 | Activity.Usage | Error | [Timestamp parameter is not valid](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg3005) +TSG3006 | Activity.Usage | Error | [Start time parameter is not valid on Create activity or Event method](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg3006) +TSG3007 | Activity.Usage | Error | [Parent context or Parent Id parameter is not valid on event](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg3007) +TSG3008 | Activity.Usage | Error | [Activity links parameters are not valid on events or context methods](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg3008) +TSG3009 | Activity.Usage | Error | [Activity tags parameter are not valid on context methods](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg3009) +TSG3010 | Activity.Usage | Error | [Escaped parameters must be a boolean](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg3010) +TSG3011 | Activity.Usage | Error | [Escaped parameters are only valid on Events, not Activity or Context methods](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg3011) +TSG3012 | Activity.Usage | Info | [There are no Activity methods defined, assumed use of Activity.Current](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg3012) +TSG3013 | Activity.Usage | Warning | [Should return the created Activity](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg3013) +TSG3014 | Activity.Usage | Warning | [Should accept an Activity to apply the Event/ Tags/ Baggage too](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg3014) +TSG3015 | Activity.Usage | Info | [Activity should be the first parameter](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg3015) +TSG3016 | Activity.Usage | Error | [Status description parameter should be a string](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg3016) +TSG3017 | Activity.Usage | Error | [Status Description parameters are only valid on Events, not Activity or Context methods](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg3017) +TSG3021 | Activity.Usage | Info | [Exception event does not use OpenTelemetry standard name](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg3021) +TSG3022 | Activity.Usage | Warning | [Activity return type should be nullable](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg3022) +TSG4000 | Metrics.Usage | Error | [No instrument defined](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg4000) +TSG4001 | Metrics.Usage | Error | [Must return void or bool](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg4001) +TSG4002 | Metrics.Usage | Error | [Auto increment counter and measurement defined](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg4002) +TSG4003 | Metrics.Usage | Error | [Multiple measurement values defined](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg4003) +TSG4004 | Metrics.Usage | Error | [No measurement value defined](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg4004) +TSG4005 | Metrics.Usage | Error | [Observable instrument requires Func](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg4005) +TSG4006 | Metrics.Usage | Error | [Invalid measurement type](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg4006) +TSG4007 | Metrics.Usage | Error | [Observable metrics cannot return bool](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg4007) +TSG4008 | Metrics.Usage | Error | [AutoCounter must return void](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg4008) +TSG4009 | Metrics.Usage | Warning | [Instrument name matches the instrument type name](https://purview.dev/docs/telemetry-sourcegenerator/diagnostics/#tsg4009) + diff --git a/src/src/SourceGenerator/AnalyzerReleases.Unshipped.md b/src/src/SourceGenerator/AnalyzerReleases.Unshipped.md new file mode 100644 index 00000000..7b845f48 --- /dev/null +++ b/src/src/SourceGenerator/AnalyzerReleases.Unshipped.md @@ -0,0 +1,7 @@ +; Unshipped analyzer release +; https://github.com/dotnet/roslyn-analyzers/blob/main/src/Microsoft.CodeAnalysis.Analyzers/ReleaseTrackingAnalyzers.Help.md + +### New Rules + +Rule ID | Category | Severity | Notes +--------|----------|----------|------- diff --git a/src/src/SourceGenerator/SourceGenerator.csproj b/src/src/SourceGenerator/SourceGenerator.csproj index 6906cf79..26a9a399 100644 --- a/src/src/SourceGenerator/SourceGenerator.csproj +++ b/src/src/SourceGenerator/SourceGenerator.csproj @@ -7,7 +7,15 @@ false - $(NoWarn);IDE0005;EnableGenerateDocumentationFile; + + $(NoWarn);IDE0005;EnableGenerateDocumentationFile;RS2003; Purview Telemetry Source Generator .NET Source Generator for interface-based telemetry generating tracing, logs, and metrics. logs;log;logger;logging;source-generator;high-performance-logging;otel;open-telemetry;telemetry;traces;tracing;metric;metrics;meter;meters;instrumentation;instruments;events;distributed-traces;distributed-tracing;melt;dotnet;aspnet; @@ -21,9 +29,13 @@ - + + + + +