From 97c02baf20b3371f22bceb4f192006ce936e9518 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 13 Aug 2025 14:40:54 +0000 Subject: [PATCH 2/3] Complete comprehensive GitHub Copilot instructions with validated build and test processes Co-authored-by: jstirnaman <212227+jstirnaman@users.noreply.github.com> --- .github/copilot-instructions.md | 443 ++++++++++++++++++++------------ 1 file changed, 273 insertions(+), 170 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index ffa9b01d0..99059b56f 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,134 +1,283 @@ -# Instructions for InfluxData Documentation +# InfluxData Documentation Repository (docs-v2) -## Purpose and scope +Always follow these instructions first and fallback to additional search and context gathering only when the information provided here is incomplete or found to be in error. -Help document InfluxData products by creating clear, accurate technical content with proper code examples, frontmatter, and formatting. +## Working Effectively -## Documentation structure +### Bootstrap, Build, and Test the Repository + +Execute these commands in order to set up a complete working environment: + +1. **Install Node.js dependencies** (takes ~4 seconds): + + ```bash + # Skip Cypress binary download due to network restrictions in CI environments + CYPRESS_INSTALL_BINARY=0 yarn install + ``` + +2. **Build the static site** (takes ~75 seconds, NEVER CANCEL - set timeout to 180+ seconds): + + ```bash + npx hugo --quiet + ``` + +3. **Start the development server** (builds in ~92 seconds, NEVER CANCEL - set timeout to 150+ seconds): + + ```bash + npx hugo server --bind 0.0.0.0 --port 1313 + ``` + + - Access at: http://localhost:1313/ + - Serves 5,359+ pages and 441 static files + - Auto-rebuilds on file changes + +4. **Alternative Docker development setup** (use if local Hugo fails): + ```bash + docker compose up local-dev + ``` + **Note**: May fail in restricted network environments due to Alpine package manager issues. + +### Testing (CRITICAL: NEVER CANCEL long-running tests) + +#### Code Block Testing (takes 5-15 minutes per product, NEVER CANCEL - set timeout to 30+ minutes): + +```bash +# Build test environment first (takes ~30 seconds, may fail due to network restrictions) +docker build -t influxdata/docs-pytest:latest -f Dockerfile.pytest . + +# Test all products (takes 15-45 minutes total) +yarn test:codeblocks:all + +# Test specific products +yarn test:codeblocks:cloud +yarn test:codeblocks:v2 +yarn test:codeblocks:telegraf +``` + +#### Link Validation (takes 10-30 minutes, NEVER CANCEL - set timeout to 45+ minutes): + +```bash +# Test all links (very long-running) +yarn test:links + +# Test specific files/products (faster) +yarn test:links content/influxdb3/core/**/*.md +yarn test:links:v3 +yarn test:links:v2 +``` + +#### Style Linting (takes 30-60 seconds): + +```bash +# Basic Vale linting +docker compose run -T vale content/**/*.md + +# Product-specific linting with custom configurations +docker compose run -T vale --config=content/influxdb3/cloud-dedicated/.vale.ini --minAlertLevel=error content/influxdb3/cloud-dedicated/**/*.md +``` + +#### JavaScript and CSS Linting (takes 5-10 seconds): + +```bash +yarn eslint assets/js/**/*.js +yarn prettier --check "**/*.{css,js,ts,jsx,tsx}" +``` + +### Pre-commit Hooks (automatically run, can be skipped if needed): + +```bash +# Run all pre-commit checks manually +yarn lint + +# Skip pre-commit hooks if necessary (not recommended) +git commit -m "message" --no-verify +``` + +## Validation Scenarios + +Always test these scenarios after making changes to ensure full functionality: + +### 1. Documentation Rendering Test + +```bash +# Start Hugo server +npx hugo server --bind 0.0.0.0 --port 1313 + +# Verify key pages load correctly (200 status) +curl -s -o /dev/null -w "%{http_code}" http://localhost:1313/influxdb3/core/ +curl -s -o /dev/null -w "%{http_code}" http://localhost:1313/influxdb/v2/ +curl -s -o /dev/null -w "%{http_code}" http://localhost:1313/telegraf/v1/ + +# Verify content contains expected elements +curl -s http://localhost:1313/influxdb3/core/ | grep -i "influxdb" +``` + +### 2. Build Output Validation + +```bash +# Verify build completes successfully +npx hugo --quiet + +# Check build output exists and has reasonable size (~529MB) +ls -la public/ +du -sh public/ + +# Verify key files exist +file public/index.html +file public/influxdb3/core/index.html +``` + +### 3. Shortcode and Formatting Test + +```bash +# Test shortcode examples page +yarn test:links content/example.md +``` + +## Repository Structure and Key Locations + +### Content Organization + +- **InfluxDB 3**: `/content/influxdb3/` (core, enterprise, cloud-dedicated, cloud-serverless, clustered, explorer) +- **InfluxDB v2**: `/content/influxdb/` (v2, cloud, enterprise_influxdb, v1) +- **Telegraf**: `/content/telegraf/v1/` +- **Other tools**: `/content/kapacitor/`, `/content/chronograf/`, `/content/flux/` +- **Shared content**: `/content/shared/` +- **Examples**: `/content/example.md` (comprehensive shortcode reference) + +### Configuration Files + +- **Hugo config**: `/config/_default/` +- **Package management**: `package.json`, `yarn.lock` +- **Docker**: `compose.yaml`, `Dockerfile.pytest` +- **Git hooks**: `lefthook.yml` +- **Testing**: `cypress.config.js`, `pytest.ini` (in test directories) +- **Linting**: `.vale.ini`, `.prettierrc.yaml`, `eslint.config.js` + +### Build and Development + +- **Hugo binary**: Available via `npx hugo` (version 0.148.2+) +- **Static assets**: `/assets/` (JavaScript, CSS, images) +- **Build output**: `/public/` (generated, ~529MB) +- **Layouts**: `/layouts/` (Hugo templates) +- **Data files**: `/data/` (YAML/JSON data for templates) + +## Technology Stack + +- **Static Site Generator**: Hugo (0.148.2+ extended) +- **Package Manager**: Yarn (1.22.22+) with Node.js (20.19.4+) +- **Testing Framework**: + - Pytest with pytest-codeblocks (for code examples) + - Cypress (for link validation and E2E tests) + - Vale (for style and writing guidelines) +- **Containerization**: Docker with Docker Compose +- **Linting**: ESLint, Prettier, Vale +- **Git Hooks**: Lefthook + +## Common Tasks and Build Times + +### Time Expectations (CRITICAL - NEVER CANCEL) + +- **Dependency installation**: 4 seconds +- **Hugo static build**: 75 seconds (NEVER CANCEL - timeout: 180+ seconds) +- **Hugo server startup**: 92 seconds (NEVER CANCEL - timeout: 150+ seconds) +- **Code block tests**: 5-15 minutes per product (NEVER CANCEL - timeout: 30+ minutes) +- **Link validation**: 10-30 minutes (NEVER CANCEL - timeout: 45+ minutes) +- **Style linting**: 30-60 seconds +- **Docker image build**: 30+ seconds (may fail due to network restrictions) + +### Network Connectivity Issues + +In restricted environments, these commands may fail due to external dependency downloads: + +- `docker build -t influxdata/docs-pytest:latest -f Dockerfile.pytest .` (InfluxData repositories, HashiCorp repos) +- `docker compose up local-dev` (Alpine package manager) +- Cypress binary installation (use `CYPRESS_INSTALL_BINARY=0`) + +Document these limitations but proceed with available functionality. + +### Validation Commands for CI + +Always run these before committing changes: + +```bash +# Format and lint code +yarn prettier --write "**/*.{css,js,ts,jsx,tsx}" +yarn eslint assets/js/**/*.js + +# Test Hugo build +npx hugo --quiet + +# Test development server startup +timeout 150 npx hugo server --bind 0.0.0.0 --port 1313 & +sleep 120 +curl -s -o /dev/null -w "%{http_code}" http://localhost:1313/ +pkill hugo +``` + +## Key Projects in This Codebase + +1. **InfluxDB 3 Documentation** (Core, Enterprise, Cloud variants) +2. **InfluxDB v2 Documentation** (OSS and Cloud) +3. **Telegraf Documentation** (agent and plugins) +4. **Supporting Tools Documentation** (Kapacitor, Chronograf, Flux) +5. **API Reference Documentation** (`/api-docs/`) +6. **Shared Documentation Components** (`/content/shared/`) + +## Important Locations for Frequent Tasks + +- **Shortcode reference**: `/content/example.md` +- **Contributing guide**: `CONTRIBUTING.md` +- **Testing guide**: `TESTING.md` +- **Product configurations**: `/data/products.yml` +- **Vale style rules**: `/.ci/vale/styles/` +- **GitHub workflows**: `/.github/workflows/` +- **Test scripts**: `/test/scripts/` +- **Hugo layouts**: `/layouts/` +- **CSS/JS assets**: `/assets/` + +## Content Guidelines and Style + +### Documentation Structure - **Product version data**: `/data/products.yml` -- **InfluxData products**: - - InfluxDB 3 Explorer - - Documentation source path: `/content/influxdb3/explorer` - - Published for the web: https://docs.influxdata.com/influxdb3/explorer/ - - InfluxDB 3 Core - - Documentation source path: `/content/influxdb3/core` - - Published for the web: https://docs.influxdata.com/influxdb3/core/ - - Code repositories: https://github.com/influxdata/influxdb, https://github.com/influxdata/influxdb3_core - - InfluxDB 3 Enterprise - - Documentation source path: `/content/influxdb3/enterprise` - - Published for the web: https://docs.influxdata.com/influxdb3/enterprise/ - - Code repositories: https://github.com/influxdata/influxdb, https://github.com/influxdata/influxdb3_enterprise - - InfluxDB Cloud Dedicated - - Documentation source path: `/content/influxdb3/cloud-dedicated` - - Published for the web: https://docs.influxdata.com/influxdb3/cloud-dedicated/ - - Code repository: https://github.com/influxdata/influxdb - - InfluxDB Cloud Serverless - - Documentation source path: `/content/influxdb3/cloud-serverless` - - Published for the web: https://docs.influxdata.com/influxdb3/cloud-serverless/ - - Code repository: https://github.com/influxdata/idpe - - InfluxDB Cloud v2 (TSM) - - Documentation source path: `/content/influxdb/cloud` - - Published for the web: https://docs.influxdata.com/influxdb/cloud/ - - Code repository: https://github.com/influxdata/idpe - - InfluxDB Clustered - - Documentation source path: `/content/influxdb3/clustered` - - Published for the web: https://docs.influxdata.com/influxdb3/clustered/ - - Code repository: https://github.com/influxdata/influxdb - - InfluxDB Enterprise v1 (1.x) - - Documentation source path: `/content/influxdb/enterprise_influxdb` - - Published for the web: https://docs.influxdata.com/enterprise_influxdb/v1/ - - Code repository: https://github.com/influxdata/influxdb - - InfluxDB OSS 1.x - - Documentation source path: `/content/influxdb/v1` - - Published for the web: https://docs.influxdata.com/influxdb/v1/ - - Code repository: https://github.com/influxdata/influxdb - - InfluxDB OSS 2.x - - Documentation source path: `/content/influxdb/v2` - - Published for the web: https://docs.influxdata.com/influxdb/v2/ - - Code repository: https://github.com/influxdata/influxdb - - Telegraf - - Documentation source path: `/content/telegraf/v1` - - Published for the web: https://docs.influxdata.com/telegraf/v1/ - - Code repository: https://github.com/influxdata/telegraf - - Kapacitor - - Documentation source path: `/content/kapacitor/v1` - - Published for the web: https://docs.influxdata.com/kapacitor/v1/ - - Code repository: https://github.com/influxdata/kapacitor - - Chronograf - - Documentation source path: `/content/chronograf/v1` - - Published for the web: https://docs.influxdata.com/chronograf/v1/ - - Code repository: https://github.com/influxdata/chronograf - - Flux - - Documentation source path: `/content/flux/v0` - - Published for the web: https://docs.influxdata.com/flux/v0/ - - Code repository: https://github.com/influxdata/flux -- **InfluxData-supported tools**: - - InfluxDB API client libraries - - Code repositories: https://github.com/InfluxCommunity - - InfluxDB 3 processing engine plugins - - Code repository: https://github.com/influxdata/influxdb3_plugins - **Query Languages**: SQL, InfluxQL, Flux (use appropriate language per product version) - **Documentation Site**: https://docs.influxdata.com -- **Repository**: https://github.com/influxdata/docs-v2 - **Framework**: Hugo static site generator -## Abbreviations and shortcuts - -- `gdd`: Google Developer Documentation style -- `3core`: InfluxDB 3 Core -- `3ent`: InfluxDB 3 Enterprise - -## Style guidelines +### Style Guidelines - Follow Google Developer Documentation style guidelines -- For API references, follow YouTube Data API style - Use semantic line feeds (one sentence per line) - Format code examples to fit within 80 characters -- Command line examples: - - Should be formatted as code blocks - - Should use long options (e.g., `--option` instead of `-o`) -- Use cURL for API examples - - Format to fit within 80 characters - - Should use `--data-urlencode` for query parameters - - Should use `--header` for headers -- Use only h2-h6 headings in content (h1 comes from frontmatter title properties) -- Use sentence case for headings -- Use GitHub callout syntax +- Use long options in command line examples (`--option` instead of `-o`) +- Use GitHub callout syntax for notes and warnings - Image naming: `project/version-context-description.png` -- Use appropriate product names and versions consistently -- Follow InfluxData vocabulary guidelines -## Markdown and shortcodes +### Markdown and Shortcodes -- Include proper frontmatter for Markdown pages in `content/**/*.md` (except for - shared content files in `content/shared/`): +Include proper frontmatter for all content pages: - ```yaml - title: # Page title (h1) - seotitle: # SEO title - list_title: # Title for article lists - description: # SEO description - menu: - product_version: - weight: # Page order (1-99, 101-199, etc.) - ``` -- Follow the shortcode examples in `content/example.md` and the documentation - for docs-v2 contributors in `CONTRIBUTING.md` -- Use provided shortcodes correctly: - - Notes/warnings: `{{% note %}}`, `{{% warn %}}` - - Product-specific: `{{% enterprise %}}`, `{{% cloud %}}` - - Tabbed content: `{{< tabs-wrapper >}}`, `{{% tabs %}}`, `{{% tab-content %}}` - - Tabbed content for code examples (without additional text): `{{< code-tabs-wrapper >}}`, `{{% code-tabs %}}`, `{{% code-tab-content %}}` - - Version links: `{{< latest >}}`, `{{< latest-patch >}}` - - API endpoints: `{{< api-endpoint >}}` - - Required elements: `{{< req >}}` - - Navigation: `{{< page-nav >}}` - - Diagrams: `{{< diagram >}}`, `{{< filesystem-diagram >}}` +```yaml +title: # Page title (h1) +seotitle: # SEO title +description: # SEO description +menu: + product_version: +weight: # Page order (1-99, 101-199, etc.) +``` -## Code examples and testing +Key shortcodes (see `/content/example.md` for full reference): -- Provide complete, working examples with proper testing annotations: +- Notes/warnings: `{{% note %}}`, `{{% warn %}}` +- Tabbed content: `{{< tabs-wrapper >}}`, `{{% tabs %}}`, `{{% tab-content %}}` +- Code examples: `{{< code-tabs-wrapper >}}`, `{{% code-tabs %}}`, `{{% code-tab-content %}}` +- Required elements: `{{< req >}}` +- API endpoints: `{{< api-endpoint >}}` + +### Code Examples and Testing + +Provide complete, working examples with pytest annotations: ```python print("Hello, world!") @@ -140,67 +289,21 @@ print("Hello, world!") Hello, world! ``` -- CLI command example: +## Troubleshooting Common Issues -```sh -influx query 'from(bucket:"example") |> range(start:-1h)' -``` +1. **"Pytest collected 0 items"**: Use `python` (not `py`) for code block language identifiers +2. **Hugo build errors**: Check `/config/_default/` for configuration issues +3. **Docker build failures**: Expected in restricted networks - document and continue with local Hugo +4. **Cypress installation failures**: Use `CYPRESS_INSTALL_BINARY=0 yarn install` +5. **Link validation slow**: Use file-specific testing: `yarn test:links content/specific-file.md` +6. **Vale linting errors**: Check `.ci/vale/styles/config/vocabularies` for accepted/rejected terms - - -``` -Table: keys: [_start, _stop, _field, _measurement] - _start:time _stop:time _field:string _measurement:string _time:time _value:float ------------------------------- ------------------------------ ---------------------- ---------------------- ------------------------------ ---------------------------- -``` - -- Include necessary environment variables -- Show proper credential handling for authenticated commands - -## API documentation - -- `/api-docs` contains OpenAPI spec files used for API reference documentation -- Follow OpenAPI specification patterns -- Match REST API examples to current implementation -- Include complete request/response examples -- Document required headers and authentication - -## Versioning and product differentiation - -- Clearly distinguish between different InfluxDB versions (1.x, 2.x, 3.x) -- Use correct terminology for each product variant -- Apply appropriate UI descriptions and screenshots -- Reference appropriate query language per version - -## Development tools - -- Vale.sh linter for style checking - - Configuration file: `.vale.ini` -- Docker for local development and testing -- pytest and pytest-codeblocks for validating code examples -- Use cypress for testing documentation UI and links -- Prettier for code formatting -- ESLint for JavaScript and TypeScript linting -- Lefthook (NPM package) for managing pre-commit hooks for quality assurance - -## Code style - -- Use modern JavaScript (ES6+) syntax - -## Related repositories - -- **Internal documentation assistance requests**: https://github.com/influxdata/DAR/issues Documentation - -## Additional instruction files +## Additional Instruction Files For specific workflows and content types, also refer to: -- **InfluxDB 3 code placeholders**: `.github/instructions/influxdb3-code-placeholders.instructions.md` - Guidelines for placeholder formatting, descriptions, and shortcode usage in InfluxDB 3 documentation -- **Contributing guidelines**: `.github/instructions/contributing.instructions.md` - Detailed style guidelines, shortcode usage, frontmatter requirements, and development workflows -- **Content-specific instructions**: Check `.github/instructions/` directory for specialized guidelines covering specific documentation patterns and requirements +- **InfluxDB 3 code placeholders**: `.github/instructions/influxdb3-code-placeholders.instructions.md` +- **Contributing guidelines**: `.github/instructions/contributing.instructions.md` +- **Content-specific instructions**: Check `.github/instructions/` directory -## Integration with specialized instructions - -When working on InfluxDB 3 documentation (Core/Enterprise), prioritize the placeholder guidelines from `influxdb3-code-placeholders.instructions.md`. - -For general documentation structure, shortcodes, and development workflows, follow the comprehensive guidelines in `contributing.instructions.md`. +Remember: This is a large documentation site with complex build processes. Patience with build times is essential, and NEVER CANCEL long-running operations. From 3b5385812a55f7d1ab56bc89bd1860e6b2900c51 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Fri, 15 Aug 2025 10:14:29 -0500 Subject: [PATCH 3/3] Apply suggestions from code review --- .github/copilot-instructions.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 99059b56f..d0fc9113f 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -217,12 +217,14 @@ pkill hugo ## Key Projects in This Codebase -1. **InfluxDB 3 Documentation** (Core, Enterprise, Cloud variants) -2. **InfluxDB v2 Documentation** (OSS and Cloud) -3. **Telegraf Documentation** (agent and plugins) -4. **Supporting Tools Documentation** (Kapacitor, Chronograf, Flux) -5. **API Reference Documentation** (`/api-docs/`) -6. **Shared Documentation Components** (`/content/shared/`) +1. **InfluxDB 3 Documentation** (Core, Enterprise, Clustered, Cloud Dedicated, Cloud Serverless, and InfluxDB 3 plugins for Core and Enterprise) +2. **InfluxDB 3 Explorer** (UI) +3. **InfluxDB v2 Documentation** (OSS and Cloud) +3. **InfuxDB v1 Documentation** (OSS and Enterprise) +4. **Telegraf Documentation** (agent and plugins) +5. **Supporting Tools Documentation** (Kapacitor, Chronograf, Flux) +6. **API Reference Documentation** (`/api-docs/`) +7. **Shared Documentation Components** (`/content/shared/`) ## Important Locations for Frequent Tasks @@ -233,7 +235,7 @@ pkill hugo - **Vale style rules**: `/.ci/vale/styles/` - **GitHub workflows**: `/.github/workflows/` - **Test scripts**: `/test/scripts/` -- **Hugo layouts**: `/layouts/` +- **Hugo layouts and shortcodes**: `/layouts/` - **CSS/JS assets**: `/assets/` ## Content Guidelines and Style @@ -269,7 +271,7 @@ weight: # Page order (1-99, 101-199, etc.) Key shortcodes (see `/content/example.md` for full reference): -- Notes/warnings: `{{% note %}}`, `{{% warn %}}` +- Notes/warnings (GitHub syntax): `> [!Note]`, `> [!Warning]` - Tabbed content: `{{< tabs-wrapper >}}`, `{{% tabs %}}`, `{{% tab-content %}}` - Code examples: `{{< code-tabs-wrapper >}}`, `{{% code-tabs %}}`, `{{% code-tab-content %}}` - Required elements: `{{< req >}}`