From 5d36ecf5656f9cfb1775b028198e690643d3f5e1 Mon Sep 17 00:00:00 2001 From: Vault Automation Date: Mon, 26 Jan 2026 15:01:59 -0500 Subject: [PATCH] Set up Copilot instructions entrypoint (#11946) (#11951) Create copilot-instructions.md for the Copilot agent to automatically apply instructions. Remove instructions for missing specific/ folder. Add code comment instructions for better commenting patterns and naming conventions. Co-authored-by: Angelo Cordon --- .github/copilot-instructions.md | 35 +++ .../generic/code_comments.instructions.md | 248 ++++++++++++++++++ .github/instructions/index.md | 33 ++- 3 files changed, 306 insertions(+), 10 deletions(-) create mode 100644 .github/copilot-instructions.md create mode 100644 .github/instructions/generic/code_comments.instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000000..ab876b799e --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,35 @@ +# GitHub Copilot Instructions for Vault Enterprise + +This repository contains coding guidelines and best practices for the Vault Enterprise project. + +## Instruction Files + +The `.github/instructions/` directory contains domain-specific coding guidelines: + +### Go Development + +- **[golang.instructions.md](instructions/generic/golang.instructions.md)**: General Go programming guidelines covering code style, package organization, error handling, and idiomatic patterns +- **[golang_tests.instructions.md](instructions/generic/golang_tests.instructions.md)**: Best practices for writing tests in Go, including table-driven tests, test structure, and integration testing + +### Ember.js UI Development + +- **[ember_general.instructions.md](instructions/generic/ember_general.instructions.md)**: Project context, repository structure, and cross-cutting concerns for Ember applications +- **[ember_js.instructions.md](instructions/generic/ember_js.instructions.md)**: JavaScript/TypeScript guidelines for Ember components and services +- **[ember_hbs.instructions.md](instructions/generic/ember_hbs.instructions.md)**: Handlebars template guidelines and best practices +- **[ember_styles.instructions.md](instructions/generic/ember_styles.instructions.md)**: SCSS styling guidelines and HashiCorp Design System usage +- **[ember_tests.instructions.md](instructions/generic/ember_tests.instructions.md)**: Testing guidelines for Ember applications + +### General Development + +- **[code_comments.instructions.md](instructions/generic/code_comments.instructions.md)**: Guidelines for writing effective code comments and self-documenting code +- **[testing.instructions.md](instructions/generic/testing.instructions.md)**: General testing best practices and guidelines + +## How These Instructions Work + +GitHub Copilot automatically applies these instructions based on the `applyTo` patterns defined in each file's frontmatter. For example: + +- Go-specific rules apply to `**/*.go` files +- Go test rules apply to `**/*_test.go` files +- Ember UI rules apply to `vault/ui/**/*` files + +When writing code, Copilot will reference the appropriate instruction files to provide context-aware suggestions that align with project standards. diff --git a/.github/instructions/generic/code_comments.instructions.md b/.github/instructions/generic/code_comments.instructions.md new file mode 100644 index 0000000000..500b00e424 --- /dev/null +++ b/.github/instructions/generic/code_comments.instructions.md @@ -0,0 +1,248 @@ +--- +applyTo: '**/*.{js,ts,go}' +description: 'Guidelines for writing effective code comments' +--- + +# Code Comments Guidelines + +## General Philosophy + +Comments should explain **why** code exists, not **what** it does. The code itself should be self-documenting through clear naming and structure. Add comments only when they provide value beyond what the code itself communicates. + +## When to Add Comments + +### Do Comment When: + +- **Explaining rationale**: Why a particular approach was chosen over alternatives + + ```javascript + // Use binary search because the list is already sorted and can be very large (100k+ items) + const index = binarySearch(sortedList, target); + ``` + +- **Documenting non-obvious behavior**: Side effects, performance characteristics, or gotchas + + ```javascript + /* + * OpenAPI schemas can reference other schemas using JSON Schema $ref + * (e.g., "$ref": "#/components/schemas/SomeSchema") + */ + const resolveRef = (spec, ref) => { ... } + ``` + +- **Explaining business logic**: Domain-specific rules or requirements + + ```go + // Per PCI DSS compliance requirements, credit card data must be encrypted at rest + encryptedData := encrypt(cardData) + ``` + +- **Warning about edge cases**: Unexpected behavior in specific scenarios + + ```javascript + /* + * Note: This will return null if the operation is a plugin-based method + * that hasn't been enabled yet + */ + const operation = findOperation(spec, operationId); + ``` + +- **Providing context for complex algorithms**: High-level explanation of what's happening + ```go + /* + * Dijkstra's algorithm for shortest path - we use a priority queue + * because the graph can have up to 10M nodes in production + */ + pq := priorityQueue.New() + ``` + +## When NOT to Add Comments + +### Don't Comment When: + +- **The code is self-explanatory**: Function and variable names clearly indicate purpose + + ```javascript + // BAD: Parse CLI arguments + const parseArgs = () => { ... } + + // GOOD: No comment needed - function name is clear + const parseArgs = () => { ... } + ``` + +- **Describing what a function does**: The function name should do this + + ```javascript + // BAD: Convert camelCase to kebab-case + const toKebabCase = (str) => { ... } + + // GOOD: No comment needed + const toKebabCase = (str) => { ... } + ``` + +- **Obvious operations**: Standard language constructs or library calls + + ```javascript + // BAD: Loop through all items + for (const item of items) { ... } + + // BAD: Create a new array + const results = []; + ``` + +- **Repeating variable names**: Comments that just restate identifiers + ```go + // BAD: userID is the user ID + userID := getUserID() + ``` + +## Improving Code Instead of Commenting + +Before adding a comment, consider if you can make the code clearer instead: + +### Extract to Named Functions + +```javascript +// BAD: +// Check if user has admin permissions and is active +if (user.role === 'admin' && user.status === 'active' && !user.suspended) { ... } + +// GOOD: +const canPerformAdminAction = (user) => + user.role === 'admin' && user.status === 'active' && !user.suspended; + +if (canPerformAdminAction(user)) { ... } +``` + +### Use Descriptive Variable Names + +```javascript +// BAD: +const d = 86400; // seconds in a day + +// GOOD: +const SECONDS_PER_DAY = 86400; +``` + +### Break Down Complex Expressions + +```javascript +// BAD: +// Calculate total with tax and discount +const total = + price * quantity * (1 + taxRate) - price * quantity * discountRate; + +// GOOD: +const subtotal = price * quantity; +const tax = subtotal * taxRate; +const discount = subtotal * discountRate; +const total = subtotal + tax - discount; +``` + +## Comment Style + +### Keep Comments Concise + +- Use brief, direct language +- Avoid overly formal or verbose explanations +- One or two sentences is usually enough + +### Update Comments When Code Changes + +- Outdated comments are worse than no comments +- Review and update comments during code changes +- Delete comments that are no longer relevant + +### Use Proper Grammar + +- Start with a capital letter +- Use complete sentences when helpful +- End with punctuation for multi-sentence comments + +## Language-Specific Guidelines + +### JavaScript/TypeScript + +- Use JSDoc for public API documentation +- For implementation comments: + - Use `/* */` for multi-line comments (easier to read, edit, and refactor) + - Use `//` for single-line comments above the relevant code + - Avoid inline comments - place comments on the line above instead + +**Example - Block comments for context:** + +```javascript +/* + * Construct request type name to match the vault-client-typescript SDK conventions. + * Example: SystemApi.mountsEnableSecretsEngine -> SystemApiMountsEnableSecretsEngineRequest + */ +const requestTypeName = constructTypeName(apiName, methodName); +``` + +**Example - Single-line above relevant code:** + +```javascript +// Remove leading # from ref path +const parts = ref.split('/').slice(1); +``` + +**Avoid inline comments:** + +```javascript +// BAD: Inline comment gets lost and makes line too long +const parts = ref.split('/').slice(1); // Remove leading # + +// GOOD: Comment above is clearer and easier to read +// Remove leading # from ref path +const parts = ref.split('/').slice(1); +``` + +### Go + +- Use complete sentences starting with the name of the element being described +- Package comments go before the package declaration +- Exported identifiers should have doc comments + +```go +// Server handles HTTP requests for the application. +// It manages connection pooling and request routing. +type Server struct { ... } +``` + +## Examples + +### Good Comment - Explains Why + +```javascript +// Use pnpm instead of yarn because the project has a packageManager field +execSync(`pnpm prettier --write "${filePath}"`, { stdio: 'pipe' }); +``` + +### Good Comment - Warns About Behavior + +```javascript +// This regex will fail on Unicode emoji - use a proper parser for user-generated content +const pattern = /[a-zA-Z0-9]/g; +``` + +### Bad Comment - States the Obvious + +```javascript +// Set the user name +user.name = newName; +``` + +### Bad Comment - Out of Date + +```javascript +// TODO: Remove this after migration to v2 API (added 2019) +const legacyData = fetchFromV1API(); +``` + +## Summary + +- **Prefer** self-documenting code over comments +- **Explain** why, not what +- **Keep** comments concise and current +- **Remove** comments that add no value +- **Update** or delete comments when code changes diff --git a/.github/instructions/index.md b/.github/instructions/index.md index 2f3b6d57fa..0814fabe54 100644 --- a/.github/instructions/index.md +++ b/.github/instructions/index.md @@ -1,16 +1,29 @@ -# Instructions +# Instructions ## Generic -The generic folder contains instructions that can simply be copied into your teams repo for reuse. They are generic problem solving rules. -- golang_test.instructions.md -Best practice for writing tests in Golang +The generic folder contains instructions that can simply be copied into your teams repo for reuse. They are generic problem solving rules. -## Specific -The specific folder contains instructions that are not intended for reuse. +- code_comments.instructions.md + Guidelines for writing effective code comments - explains when to comment and when to write self-documenting code instead -config.instructions.md -Guidance for the pkg/config package in the terraform-enterprise repository, providing additional context, such as the requirement to consider backwards compatability. +- golang_tests.instructions.md + Best practices for writing tests in Golang -style.instructions.md -Guidance for writing documentation. Used in the web-unified-docs-internal repo. +- ember_general.instructions.md + General guidelines for HashiCorp Ember.js UI applications + +- ember_hbs.instructions.md + Guidelines for Handlebars templates in Ember applications + +- ember_js.instructions.md + Guidelines for JavaScript/TypeScript in Ember applications + +- ember_styles.instructions.md + Guidelines for SCSS styling in Ember applications + +- ember_tests.instructions.md + Guidelines for testing Ember applications + +- testing.instructions.md + General testing best practices and guidelines