Merge pull request #6092 from influxdata/jts-copilot-instructions

chore(qol): Build custom CoPilot instructions from CONTRIBUTING.md:

.github/instructions/influxdb3-code-placeholders.instructions.md

@@ -0,0 +1,89 @@
+---
+mode: 'edit'
+applyTo: "content/{influxdb3/core,influxdb3/enterprise,shared/influxdb3*}/**"
+---
+## Best Practices
+
+- Use UPPERCASE for placeholders to make them easily identifiable
+- Don't use pronouns in placeholders (e.g., "your", "this")
+- List placeholders in the same order they appear in the code
+- Provide clear descriptions including:
+- - Expected data type or format
+- - Purpose of the value
+- - Any constraints or requirements
+- Mark optional placeholders as "Optional:" in their descriptions
+- Placeholder key descriptions should fit the context of the code snippet
+- Include examples for complex formats
+
+## Writing Placeholder Descriptions
+
+Descriptions should follow consistent patterns:
+
+1. **Admin Authentication tokens**: 
+   - Recommended: "a {{% token-link "admin" %}} for your {{< product-name >}} instance"
+   - Avoid: "your token", "the token", "an authorization token"
+2. **Database resource tokens**:
+   - Recommended: "your {{% token-link "database" %}}"{{% show-in "enterprise" %}} with permissions on the specified database{{% /show-in %}}
+   - Avoid: "your token", "the token", "an authorization token"
+3. **Database names**:
+   - Recommended: "the name of the database to [action]" 
+   - Avoid: "your database", "the database name"
+4. **Conditional content**:
+   - Use `{{% show-in "enterprise" %}}` for content specific to enterprise versions
+   - Example: "your {{% token-link "database" %}}{{% show-in "enterprise" %}} with permission to query the specified database{{% /show-in %}}"
+
+## Common placeholders for InfluxDB 3
+
+- `AUTH_TOKEN`: your {{% token-link %}}
+- `DATABASE_NAME`: the database to use
+- `TABLE_NAME`: Name of the table/measurement to query or write to
+- `NODE_ID`: Node ID for a specific node in a cluster
+- `CLUSTER_ID`: Cluster ID for a specific cluster
+- `HOST`: InfluxDB server hostname or URL
+- `PORT`: InfluxDB server port (typically 8181)
+- `QUERY`: SQL or InfluxQL query string
+- `LINE_PROTOCOL`: Line protocol data for writes
+- `PLUGIN_FILENAME`: Name of plugin file to use
+- `CACHE_NAME`: Name for a new or existing cache
+
+## Hugo shortcodes in Markdown
+
+- `{{% code-placeholders "PLACEHOLDER1|PLACEHOLDER2" %}}`: Use this shortcode to define placeholders in code snippets.
+- `{{% /code-placeholders %}}`: End the shortcode.
+- `{{% code-placeholder-key %}}`: Use this shortcode to define a specific placeholder key.
+- `{{% /code-placeholder-key %}}`: End the specific placeholder key shortcode.
+
+## Language-Specific Placeholder Formatting
+
+- **Bash/Shell**: Use uppercase variables with no quotes or prefix
+  ```bash
+  --database DATABASE_NAME
+  ```
+- Python: Use string literals with quotes
+  ```python
+  database_name='DATABASE_NAME'
+  ```
+- JSON: Use key-value pairs with quotes
+  ```json
+  {
+    "database": "DATABASE_NAME"
+  }
+  ```
+
+## Real-World Examples from Documentation
+
+### InfluxDB CLI Commands
+This pattern appears frequently in CLI documentation:
+
+{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}}
+```bash
+influxdb3 write \
+  --database DATABASE_NAME \
+  --token AUTH_TOKEN \
+  --precision ns
+{{% /code-placeholders %}}
+
+Replace the following placeholders with your values:
+
+{{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to write to
+{{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "database" %}}{{% show-in "enterprise" %}} with write permissions on the specified database{{% /show-in %}}

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing to InfluxData Documentation
 
-## Sign the InfluxData CLA
+### Sign the InfluxData CLA
 
 The InfluxData Contributor License Agreement (CLA) is part of the legal framework
 for the open source ecosystem that protects both you and InfluxData.

build-scripts/build-copilot-instructions.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+/**
+ * Script to generate GitHub Copilot instructions
+ * for InfluxData documentation.
+ */
+import fs from 'fs';
+import path from 'path';
+import process from 'process';
+import { execSync } from 'child_process';
+
+// Get the current file path and directory
+export { buildContributingInstructions };
+
+(async () => {
+  try {
+    await buildContributingInstructions();
+  } catch (error) {
+    console.error('Error generating Copilot instructions:', error);
+  }
+})();
+
+/** Build instructions from CONTRIBUTING.md
+ * This script reads CONTRIBUTING.md, formats it appropriately,
+ * and saves it to .github/instructions/contributing.instructions.md
+ */
+function buildContributingInstructions() {
+  // Paths
+  const contributingPath = path.join(process.cwd(), 'CONTRIBUTING.md');
+  const instructionsDir = path.join(process.cwd(), '.github', 'instructions');
+  const instructionsPath = path.join(
+    instructionsDir,
+    'contributing.instructions.md'
+  );
+
+  // Ensure the instructions directory exists
+  if (!fs.existsSync(instructionsDir)) {
+    fs.mkdirSync(instructionsDir, { recursive: true });
+  }
+
+  // Read the CONTRIBUTING.md file
+  let content = fs.readFileSync(contributingPath, 'utf8');
+
+  // Format the content for Copilot instructions with applyTo attribute
+  content = `---
+applyTo: "content/**/*.md, layouts/**/*.html"
+---
+
+# GitHub Copilot Instructions for InfluxData Documentation
+
+## Purpose and scope
+
+GitHub Copilot should help document InfluxData products
+by creating clear, accurate technical content with proper
+code examples, frontmatter, shortcodes, and formatting.
+
+${content}`;
+
+  // Write the formatted content to the instructions file
+  fs.writeFileSync(instructionsPath, content);
+
+  console.log(`✅ Generated Copilot instructions at ${instructionsPath}`);
+
+  // Add the file to git if it has changed
+  try {
+    const gitStatus = execSync(
+      `git status --porcelain "${instructionsPath}"`
+    ).toString();
+    if (gitStatus.trim()) {
+      execSync(`git add "${instructionsPath}"`);
+      console.log('✅ Added instructions file to git staging');
+    }
+  } catch (error) {
+    console.warn('⚠️  Could not add instructions file to git:', error.message);
+  }
+}

compose.yaml

@@ -449,6 +449,9 @@ services:
       - type: bind
         source: ./content
         target: /app/content
+      - type: bind
+        source: ./CONTRIBUTING.md
+        target: /app/CONTRIBUTING.md
 volumes:
   test-content:
   cloud-tmp:

lefthook.yml

@@ -5,10 +5,13 @@
 pre-commit:
   parallel: true
   commands:
+    build-copilot-instructions:
+      glob: "CONTRIBUTING.md"
+      run: yarn build:copilot-instructions 
     # Report linting warnings and errors, don't output files to stdout
     lint-markdown:
       tags: lint
-      glob: 'content/*.md'
+      glob: "{CONTRIBUTING.md,content/*.md}"
       run: |
         docker compose run --rm --name remark-lint remark-lint '{staged_files}'
     cloud-lint:

package.json

@@ -41,6 +41,7 @@
   },
   "scripts": {
     "build:pytest:image": "docker build -t influxdata/docs-pytest:latest -f Dockerfile.pytest .",
+    "build:copilot-instructions": "node ./build-scripts/build-copilot-instructions.js",
     "lint": "LEFTHOOK_EXCLUDE=test lefthook run pre-commit && lefthook run pre-push",
     "pre-commit": "lefthook run pre-commit",
     "test": "echo \"Run 'yarn test:e2e', 'yarn test:links', 'yarn test:codeblocks:all' or a specific test command. e2e and links test commands can take a glob of file paths to test. Some commands run automatically during the git pre-commit and pre-push hooks.\" && exit 0",