From 0b1533b938b2ae2caa3c76c055dc9a095d53f072 Mon Sep 17 00:00:00 2001 From: =?utf8?q?J=C3=A9r=C3=B4me=20Benoit?= Date: Sun, 5 Oct 2025 14:19:59 +0200 Subject: [PATCH] chore: refine 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 | 50 ++++++++++++++++++++++----------- tests/ocpp-server/README.md | 2 +- 2 files changed, 35 insertions(+), 17 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 305b5cc8..fb3cf97c 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -10,13 +10,14 @@ These instructions guide GitHub Copilot to generate changes consistent with this ## 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. +- **Algorithmic**: prefer algorithms or heuristics solving the problem while 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. +- **Documentation standards**: must follow established standards for programming languages. ## Options and configuration @@ -40,22 +41,18 @@ These instructions guide GitHub Copilot to generate changes consistent with this - **Interpretation**: include threshold guidelines; avoid overclaiming certainty. - **Artifacts**: timestamp outputs; include configuration metadata. -## Implementation guidance for Copilot +## Documentation conventions -- **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 and OCPP-specific conventions below. -- **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. +- **Clarity**: plain, unambiguous language; avoid marketing jargon and speculation. +- **Concision**: remove boilerplate; state facts directly without redundant phrasing. +- **Structure**: use consistent section ordering; follow stable patterns for comparable content. +- **Timeliness**: document current state; exclude historical evolution (except brief API breaking change notes). +- **Terminology**: use correct and consistent terminology; distinguish clearly between related concepts. +- **Exhaustivity**: cover all user-facing behavior and constraints; omit internal implementation details unless necessary for usage. +- **Pertinence**: include information that aids understanding or usage; remove tangential content. +- **No duplication**: maintain single authoritative documentation source; reference other sources rather than copying. + +Documentation serves as an operational specification, not narrative prose. ## TypeScript/Node.js conventions @@ -77,6 +74,27 @@ These instructions guide GitHub Copilot to generate changes consistent with this - **UUID tracking**: Use UUIDs to correlate requests with responses; store pending operations in Maps with UUID keys. - **Response handling**: Wait for all expected responses before resolving broadcast requests. +## Implementation guidance for Copilot + +- **Before coding**: + - Locate and analyze thoroughly existing relevant code. + - Identify existing code architecture, design patterns, canonical defaults, naming patterns and coding styles. +- **When coding**: + - Follow identified design patterns, naming patterns and coding styles. + - Prioritize algorithmic efficiency. + - Write minimal, verifiable changes that preserve existing behavior when possible. + - Follow TypeScript/Node.js and OCPP-specific conventions above. +- **When adding a tunable**: + - Add to canonical 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 documentations atomically. +- **When documenting**: + - Follow documentation conventions above. + ## Quality gates - Build/lint/type checks pass (where applicable). diff --git a/tests/ocpp-server/README.md b/tests/ocpp-server/README.md index c1453840..47abe385 100644 --- a/tests/ocpp-server/README.md +++ b/tests/ocpp-server/README.md @@ -12,7 +12,7 @@ Install poetry: pipx install poetry ``` -or using your OS packages manager. +or by using your OS packages manager. Then install dependencies: -- 2.43.0