From 9b3512dac11cefdcd445c7a2d22ec77a091ae088 Mon Sep 17 00:00:00 2001 From: =?utf8?q?J=C3=A9r=C3=B4me=20Benoit?= Date: Sat, 4 Oct 2025 15:45:51 +0200 Subject: [PATCH] chore: github copilot instructions MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Signed-off-by: Jérôme Benoit --- .github/copilot-instructions.md | 140 ++++++++++++++++++++++++++++++++ 1 file changed, 140 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 000000000..f7ef0dc19 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,140 @@ +# Copilot Instructions (repository-wide, language-agnostic) + +These instructions guide GitHub Copilot to generate changes consistent with this repository's conventions, regardless of programming language. + +## Glossary + +- **Tunables**: user-adjustable parameters that shape behavior, exposed via options or configuration files. +- **Canonical defaults**: the single, authoritative definition of all tunables and their defaults. + +## Core principles + +- **Design patterns**: prefer established patterns (e.g., factory, singleton, strategy) for code organization and extensibility. +- **Algorithmic**: prefer algorithms or heuristics minimizing time and space complexity. +- **DRY**: avoid duplication of logic, data, and naming. Factor out commonalities. +- **Single source of truth**: maintain a canonical defaults map for configuration tunables. Derive all user-facing options automatically. +- **Naming coherence**: prefer semantically accurate names across code, documentation, directories, and outputs. Avoid synonyms that create ambiguity. +- **English-only**: code, tests, logs, comments, and documentation must be in English. +- **Small, verifiable changes**: prefer minimal diffs that keep public behavior stable unless explicitly requested. +- **Tests-first mindset**: add or update minimal tests before refactoring or feature changes. + +## Options and configuration + +- **Dynamic generation**: derive CLI and configuration options automatically from canonical defaults. Avoid manual duplication. +- **Merge precedence**: defaults < user options < explicit overrides (highest precedence). Never silently drop user-provided values. +- **Validation**: enforce constraints (choices, ranges, types) at the option layer with explicit typing. +- **Help text**: provide concrete examples for complex options, especially override mechanisms. + +## Statistical conventions + +- **Hypothesis testing**: use a single test statistic (e.g., t-test) when possible. +- **Divergence metrics**: document direction explicitly (e.g., KL(A||B) vs KL(B||A)); normalize distributions; add numerical stability measures. +- **Effect sizes**: report alongside test statistics and p-values; use standard formulas; document directional interpretation. +- **Distribution comparisons**: use multiple complementary metrics (parametric and non-parametric). +- **Multiple testing**: document corrections or acknowledge their absence. + +## Reporting conventions + +- **Structure**: start with run configuration, then stable section order for comparability. +- **Format**: use structured formats (e.g., tables) for metrics; avoid free-form text for data. +- **Interpretation**: include threshold guidelines; avoid overclaiming certainty. +- **Artifacts**: timestamp outputs; include configuration metadata. + +## Implementation guidance for Copilot + +- **Before coding**: + - Locate and analyze thoroughly relevant existing code. + - Identify code architecture and design patterns. + - Identify canonical defaults and naming patterns. +- **When coding**: + - Follow TypeScript/Node.js conventions. +- **When adding a tunable**: + - Add to defaults with safe value. + - Update documentation and serialization. +- **When implementing analytical methods**: + - Follow statistical conventions above. +- **When refactoring**: + - Keep APIs stable; provide aliases if renaming. + - Update code, tests, and docs atomically. + +## TypeScript/Node.js conventions + +- **Naming**: Use camelCase for variables/functions/methods, PascalCase for classes/types/enums/interfaces. +- **Async operations**: Prefer async/await over raw Promises; handle rejections explicitly with try/catch. +- **Error handling**: Use typed errors with structured properties when applicable. +- **Worker communication**: Use broadcast channels for decoupled worker<->main thread messaging. +- **Null safety**: Avoid non-null assertions (!); use optional chaining (?.) and nullish coalescing (??). +- **Type safety**: Prefer explicit types over any; use type guards and discriminated unions where appropriate. +- **Promise patterns**: Return Promises from async operations; store resolvers/rejectors in Maps for request/response flows. +- **Immutability**: Avoid mutating shared state; clone objects before modification when needed. + +## Quality gates + +- Build/lint/type checks pass (where applicable). +- Tests pass (where applicable). +- Documentation updated to reflect changes. +- Logs use appropriate levels (error, warn, info, debug). +- PR title and commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) format. + +## Examples + +### Naming coherence + +**Good** (consistent style, clear semantics): + +```typescript +const thresholdValue = 0.06 +const processingMode = 'piecewise' +type ChargingStationStatus = 'Available' | 'Preparing' | 'Charging' +``` + +**Bad** (mixed styles, ambiguous): + +```typescript +const threshold_value = 0.06 // inconsistent case style +const thresholdAim = 0.06 // synonym creates ambiguity +type charging_station_status // wrong casing for type +``` + +### Promise-based request/response pattern + +**Good** (proper async flow): + +```typescript +protected handleProtocolRequest( + uuid: string, + procedureName: ProcedureName, + payload: RequestPayload +): Promise { + return new Promise((resolve, reject) => { + this.pendingRequests.set(uuid, { reject, resolve }) + this.sendBroadcastChannelRequest(uuid, procedureName, payload) + }) +} +``` + +**Bad** (returns void, no Promise): + +```typescript +protected handleProtocolRequest( + uuid: string, + procedureName: ProcedureName, + payload: RequestPayload +): void { + this.sendBroadcastChannelRequest(uuid, procedureName, payload) + // Response never reaches caller! +} +``` + +### Statistical reporting + +```markdown +| Metric | Value | Interpretation | +| ----------- | ----- | --------------------- | +| KL(A‖B) | 0.023 | < 0.1: low divergence | +| Effect size | 0.12 | small to medium | +``` + +--- + +By following these instructions, Copilot should propose changes that are consistent and maintainable across languages. -- 2.43.0