diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index bf7d42ba5a3..a17472617fc 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -46,6 +46,25 @@ Each extension follows the standard VS Code extension structure with `package.js 3. **Follow imports**: Check what files import the problematic module 4. **Check test files**: Often reveal usage patterns and expected behavior +## Validating TypeScript changes + +You MUST check compilation output before running ANY script or declaring work complete! + +1. **ALWAYS** check the `VS Code - Build` watch task output for compilation errors +2. **NEVER** run tests if there are compilation errors +3. **NEVER** use `npm run compile` to compile TypeScript files, always check task output +4. **FIX** all compilation errors before moving forward + +### TypeScript compilation steps +- Monitor the `VS Code - Build` task outputs for real-time compilation errors as you make changes +- This task runs `Core - Build` and `Ext - Build` to incrementally compile VS Code TypeScript sources and built-in extensions +- Start the task if it's not already running in the background + +### TypeScript validation steps +- Use run test tool or `scripts/test.sh` (`scripts\test.bat` on Windows) for unit tests (add `--grep ` to filter tests) +- Use `scripts/test-integration.sh` (or `scripts\test-integration.bat` on Windows) for integration tests +- Use `npm run valid-layers-check` to check for layering issues + ## Coding Guidelines ### Indentation diff --git a/.github/instructions/telemetry.instructions.md b/.github/instructions/telemetry.instructions.md new file mode 100644 index 00000000000..ab8c01bca92 --- /dev/null +++ b/.github/instructions/telemetry.instructions.md @@ -0,0 +1,114 @@ +--- +applyTo: '**/*.ts' +description: Telemetry Implementation Guide +--- + +Patterns for GDPR-compliant telemetry in VS Code with proper type safety and privacy protection. + +## Implementation Pattern + +### 1. Define Types +```typescript +type MyFeatureEvent = { + action: string; + duration: number; + success: boolean; + errorCode?: string; +}; + +type MyFeatureClassification = { + action: { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; comment: 'The action performed.' }; + duration: { classification: 'SystemMetaData'; purpose: 'PerformanceAndHealth'; isMeasurement: true; comment: 'Time in milliseconds.' }; + success: { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; isMeasurement: true; comment: 'Whether action succeeded.' }; + errorCode: { classification: 'SystemMetaData'; purpose: 'PerformanceAndHealth'; comment: 'Error code if action failed.' }; + owner: 'yourGitHubUsername'; + comment: 'Tracks MyFeature usage and performance.'; +}; +``` + +### 2.1. Send Event +```typescript +this.telemetryService.publicLog2('myFeatureAction', { + action: 'buttonClick', + duration: 150, + success: true +}); +``` + +### 2.2. Error Events +For error-specific telemetry with stack traces or error messages: +```typescript +type MyErrorEvent = { + operation: string; + errorMessage: string; + duration?: number; +}; + +type MyErrorClassification = { + operation: { classification: 'SystemMetaData'; purpose: 'PerformanceAndHealth'; comment: 'The operation that failed.' }; + errorMessage: { classification: 'CallstackOrException'; purpose: 'PerformanceAndHealth'; comment: 'The error message.' }; + duration: { classification: 'SystemMetaData'; purpose: 'PerformanceAndHealth'; isMeasurement: true; comment: 'Time until failure.' }; + owner: 'yourGitHubUsername'; + comment: 'Tracks MyFeature errors for reliability.'; +}; + +this.telemetryService.publicLogError2('myFeatureError', { + operation: 'fileRead', + errorMessage: error.message, + duration: 1200 +}); +``` + +### 3. Service Injection +```typescript +constructor( + @ITelemetryService private readonly telemetryService: ITelemetryService, +) { super(); } +``` + +## GDPR Classifications & Purposes + +**Classifications (choose the most restrictive):** +- `SystemMetaData` - **Most common.** Non-personal system info, user preferences, feature usage, identifiers (extension IDs, language types, counts, durations, success flags) +- `CallstackOrException` - Error messages, stack traces, exception details. **Only for actual error information.** +- `PublicNonPersonalData` - Data already publicly available (rare) + +**Purposes (combine with different classifications):** +- `FeatureInsight` - **Default.** Understanding how features are used, user behavior patterns, feature adoption +- `PerformanceAndHealth` - **For errors & performance.** Metrics, error rates, performance measurements, diagnostics + +**Required Properties:** +- `comment` - Clear explanation of what the field contains and why it's collected +- `owner` - GitHub username (infer from branch or ask) +- `isMeasurement: true` - **Required** for all numeric values flags used in calculations + +## Error Events + +Use `publicLogError2` for errors with `CallstackOrException` classification: + +```typescript +this.telemetryService.publicLogError2('myFeatureError', { + errorMessage: error.message, + errorCode: 'MYFEATURE_001', + context: 'initialization' +}); +``` + +## Naming & Privacy Rules + +**Naming Conventions:** +- Event names: `camelCase` with context (`extensionActivationError`, `chatMessageSent`) +- Property names: specific and descriptive (`agentId` not `id`, `durationMs` not `duration`) +- Common patterns: `success/hasError/isEnabled`, `sessionId/extensionId`, `type/kind/source` + +**Critical Don'ts:** +- ❌ No PII (usernames, emails, file paths, content) +- ❌ Missing `owner` field in classification (infer from branch name or ask user) +- ❌ Vague comments ("user data" → "selected language identifier") +- ❌ Wrong classification +- ❌ Missing `isMeasurement` on numeric metrics + +**Privacy Requirements:** +- Minimize data collection to essential insights only +- Use hashes/categories instead of raw values when possible +- Document clear purpose for each data point diff --git a/.github/instructions/typescript.instructions.md b/.github/instructions/typescript.instructions.md deleted file mode 100644 index f5bd2aaae88..00000000000 --- a/.github/instructions/typescript.instructions.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -applyTo: '**/*.ts' ---- - -# VS Code Copilot Development Instructions for TypeScript - -You MUST check compilation output before running ANY script or declaring work complete! - -1. **ALWAYS** check the "VS Code - Build" task output for compilation errors -3. **NEVER** run tests if there are compilation errors -3. **NEVER** use `npm run compile` to compile TypeScript files, always check task output -4. **FIX** all compilation errors before moving forward - -## TypeScript compilation steps - -Typescript compilation errors can be found by running the "VS Code - Build" task, which compiles the VS Code TypeScript sources and the built-in extensions: -- This background task may already be running from previous development sessions -- If not already running, start the task to get real-time compilation feedback -- The task provides incremental compilation, so it will automatically recompile when files change - -## TypeScript validation steps -- Use `scripts/test.sh` (or `scripts\test.bat` on Windows) for unit tests (add `--grep ` to filter tests) -- Use `scripts/test-integration.sh` (or `scripts\test-integration.bat` on Windows) for integration tests -- Use `npm run valid-layers-check` to check for layering issues -