Merge branch 'master' into 6021-add-schedule-plugin-test-docs

Author: MeelahMe

.github/instructions/contributing.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 %}}

.github/instructions/influxdb3-code-placeholders.instructions.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.

CONTRIBUTING.md

@@ -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);
+  }
+}

build-scripts/build-copilot-instructions.js

@@ -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:

compose.yaml

@@ -16,5 +16,6 @@ source: /shared/influxdb3-write-guides/best-practices/optimize-writes.md
 ---
 
 <!--
-The content for this page is at content/shared/influxdb3-write-guides/best-practices/optimize-writes.md
+The content for this page is at
+//SOURCE content/shared/influxdb3-write-guides/best-practices/optimize-writes.md
 -->

content/influxdb3/core/write-data/best-practices/optimize-writes.md

@@ -16,5 +16,6 @@ source: /shared/influxdb3-write-guides/best-practices/schema-design.md
 ---
 
 <!--
-The content for this page is at content/shared/influxdb3-write-guides/best-practices/schema-design.md
+The content for this page is at
+//SOURCE content/shared/influxdb3-write-guides/best-practices/schema-design.md
 -->

content/influxdb3/core/write-data/best-practices/schema-design.md

@@ -16,5 +16,6 @@ source: /shared/influxdb3-write-guides/best-practices/optimize-writes.md
 ---
 
 <!--
-The content for this page is at content/shared/influxdb3-write-guides/best-practices/optimize-writes.md
+The content for this page is at
+//SOURCE content/shared/influxdb3-write-guides/best-practices/optimize-writes.md
 -->

content/influxdb3/enterprise/write-data/best-practices/optimize-writes.md

@@ -16,5 +16,6 @@ source: /shared/influxdb3-write-guides/best-practices/schema-design.md
 ---
 
 <!--
-The content for this page is at content/shared/influxdb3-write-guides/best-practices/schema-design.md
+The content for this page is at
+//SOURCE content/shared/influxdb3-write-guides/best-practices/schema-design.md
 -->

content/influxdb3/enterprise/write-data/best-practices/schema-design.md

@@ -3,7 +3,8 @@ Use these tips to optimize performance and system overhead when writing data to
 {{< product-name >}}.
 
 - [Batch writes](#batch-writes)
-- [Sort tags by key](#sort-tags-by-key)
+{{% hide-in "enterprise,core" %}}- [Sort tags by key](#sort-tags-by-key){{% /hide-in %}}
+{{% show-in "enterprise,core" %}}- [On first write, sort tags by query priority](#on-first-write-sort-tags-by-query-priority){{% /show-in %}}
 - [Use the coarsest time precision possible](#use-the-coarsest-time-precision-possible)
 - [Use gzip compression](#use-gzip-compression)
   - [Enable gzip compression in Telegraf](#enable-gzip-compression-in-telegraf)
@@ -34,6 +35,8 @@ Write data in batches to minimize network overhead when writing data to InfluxDB
 > The optimal batch size is 10,000 lines of line protocol or 10 MBs, whichever
 > threshold is met first.
 
+{{% hide-in "enterprise,core" %}}
+
 ## Sort tags by key
 
 Before writing data points to InfluxDB, sort tags by key in lexicographic order.
@@ -49,6 +52,31 @@ measurement,tagC=therefore,tagE=am,tagA=i,tagD=i,tagB=think fieldKey=fieldValue
 measurement,tagA=i,tagB=think,tagC=therefore,tagD=i,tagE=am fieldKey=fieldValue 1562020262
 ```
 
+{{% /hide-in %}}
+
+{{% show-in "enterprise,core" %}}
+
+## On first write, sort tags by query priority
+
+The first write to a table in {{% product-name %}} determines the physical column
+order in storage, and that order has a direct impact on query performance.
+Columns that appear earlier are typically faster to filter and access during
+query execution.
+
+Sort your tags by query priority when performing the initial write to a table.
+Place the most commonly queried tags first—those you frequently use in `WHERE`
+clauses or joins—followed by less frequently queried ones. For example, if most
+of your queries filter by `region` and then by `host`, structure your first
+write so that `region` comes before `host`.
+
+> [!Important]
+> Column order is determined on the first write and cannot be changed afterward.
+> Tags added after the first write are added last in the column sort order.
+> Plan your schema with your query workload in mind to ensure the best long-term
+> performance.
+
+{{% /show-in %}}
+
 ## Use the coarsest time precision possible
 
 {{< product-name >}} supports up to nanosecond timestamp precision. However,