Skip to content

Commit 3d3de0f

Browse files
jstirnamanjstirnaman
committed
chore(ci): copilot-instructions: specify content paths, related repositories, and additional guidelines
1 parent a0dfc1c commit 3d3de0f

File tree

1 file changed

+121
-65
lines changed

1 file changed

+121
-65
lines changed

‎.github/copilot-instructions.md

Lines changed: 121 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -1,90 +1,146 @@
11
# GitHub Copilot Instructions for InfluxData Documentation
22

3-
GitHub Copilot should assist with writing and styling InfluxData documentation according to the following guidelines:
4-
5-
## Documentation Overview
6-
7-
- Documentation covers InfluxDB and associated products (Telegraf, client libraries)
8-
- Primary documentation site: https://docs.influxdata.com
9-
- Source repository: https://github.com/influxdata/docs-v2
10-
- Hugo static site generator is used to build the documentation
11-
12-
## Products and Query Languages
13-
14-
When working with product-specific content, identify the appropriate product from:
15-
16-
- InfluxDB OSS (1.x, 2.x, 3 Core)
17-
- InfluxDB Enterprise
18-
- InfluxDB Cloud variants (TSM, Dedicated, Serverless)
19-
- InfluxDB 3 Clustered
20-
- Telegraf
21-
22-
Identify appropriate query language (SQL, InfluxQL, Flux) based on product version.
23-
24-
## Style Standards
3+
## Purpose and Scope
4+
5+
GitHub Copilot should help document InfluxData products by creating clear, accurate technical content with proper code examples, frontmatter, and formatting.
6+
7+
## Documentation Structure
8+
9+
- **Products**:
10+
- InfluxDB OSS 1.x
11+
- Documentation source path: `/content/influxdb/v1`
12+
- Code repository: https://github.com/influxdata/influxdb
13+
- InfluxDB OSS 2.x
14+
- Documentation source path: `/content/influxdb/v2`
15+
- Code repository: https://github.com/influxdata/influxdb
16+
- InfluxDB 3 Core
17+
- Documentation source path: `/content/influxdb3/core`
18+
- Code repositories: https://github.com/influxdata/influxdb, https://github.com/influxdata/influxdb3_core
19+
- InfluxDB Enterprise v1 (1.x)
20+
- Documentation source path: `/content/influxdb/enterprise_influxdb`
21+
- Code repository: https://github.com/influxdata/influxdb
22+
- InfluxDB Cloud v2 (TSM)
23+
- Documentation source path: `/content/influxdb/cloud`
24+
- Code repository: https://github.com/influxdata/idpe
25+
- InfluxDB 3 Cloud Dedicated
26+
- Documentation source path: `/content/influxdb3/cloud-dedicated`
27+
- Code repository: https://github.com/influxdata/influxdb
28+
- InfluxDB 3 Cloud Serverless
29+
- Documentation source path: `/content/influxdb3/cloud-serverless`
30+
- Code repository: https://github.com/influxdata/idpe
31+
- InfluxDB 3 Clustered
32+
- Documentation source path: `/content/influxdb3/clustered`
33+
- Code repository: https://github.com/influxdata/influxdb
34+
- Telegraf
35+
- Documentation source path: `/content/telegraf/v1`
36+
- Code repository: https://github.com/influxdata/telegraf
37+
- Kapacitor
38+
- Documentation source path: `/content/kapacitor/v1`
39+
- Code repository: https://github.com/influxdata/kapacitor
40+
- Chronograf
41+
- Documentation source path: `/content/chronograf/v1`
42+
- Code repository: https://github.com/influxdata/chronograf
43+
- Flux
44+
- Documentation source path: `/content/flux/v0`
45+
- Code repository: https://github.com/influxdata/flux
46+
- **InfluxData-supported tools**:
47+
- InfluxDB API client libraries
48+
- Code repositories: https://github.com/InfluxCommunity
49+
- InfluxDB 3 processing engine plugins
50+
- Code repository: https://github.com/influxdata/influxdb3_plugins
51+
- **Query Languages**: SQL, InfluxQL, Flux (use appropriate language per product version)
52+
- **Documentation Site**: https://docs.influxdata.com
53+
- **Repository**: https://github.com/influxdata/docs-v2
54+
- **Framework**: Hugo static site generator
55+
56+
## Style Guidelines
2557

2658
- Follow Google Developer Documentation style guidelines
27-
- For REST API references, follow YouTube Data API style
28-
- Use semantic line feeds (one sentence per line) for easier diff comparison
59+
- For API references, follow YouTube Data API style
60+
- Use semantic line feeds (one sentence per line)
2961
- Use only h2-h6 headings in content (h1 comes from frontmatter)
30-
- Image naming format: `project/version-context-description.png`
31-
32-
## Markdown Conventions
62+
- Use sentence case for headings
63+
- Use GitHub callout syntax
64+
- Image naming: `project/version-context-description.png`
65+
- Use appropriate product names and versions consistently
66+
- Follow InfluxData vocabulary guidelines
3367

34-
- Use standard Markdown for most content
35-
- Include proper frontmatter for each page (title, description, weight, etc.)
36-
- Use available shortcodes for notes, warnings, tabbed content, and other special formatting
37-
- Observe semantic line feeds (one sentence per line)
38-
- Use proper heading hierarchy (h2-h6 only)
68+
## Markdown and Shortcodes
3969

40-
## Shortcodes
70+
- Include proper frontmatter for each page:
4171

42-
Help use the following shortcodes appropriately:
72+
```yaml
73+
title: # Page title (h1)
74+
seotitle: # SEO title
75+
list_title: # Title for article lists
76+
description: # SEO description
77+
menu:
78+
product_version:
79+
weight: # Page order (1-99, 101-199, etc.)
80+
```
4381
44-
- Notes and warnings: `{{% note %}}` and `{{% warn %}}`
45-
- Product-specific content: `{{% enterprise %}}`, `{{% cloud %}}`
46-
- Tabbed content: `{{< tabs-wrapper >}}`, `{{% tabs %}}`, `{{% tab-content %}}`
47-
- Latest version links: `{{< latest >}}`, `{{< latest-patch >}}`
48-
- API endpoints: `{{< api-endpoint >}}`
49-
- Required elements: `{{< req >}}`
50-
- Navigation: `{{< page-nav >}}`
51-
- Diagrams: `{{< diagram >}}`, `{{< filesystem-diagram >}}`
82+
- Use provided shortcodes correctly:
83+
- Notes/warnings: `{{% note %}}`, `{{% warn %}}`
84+
- Product-specific: `{{% enterprise %}}`, `{{% cloud %}}`
85+
- Tabbed content: `{{< tabs-wrapper >}}`, `{{% tabs %}}`, `{{% tab-content %}}`
86+
- Version links: `{{< latest >}}`, `{{< latest-patch >}}`
87+
- API endpoints: `{{< api-endpoint >}}`
88+
- Required elements: `{{< req >}}`
89+
- Navigation: `{{< page-nav >}}`
90+
- Diagrams: `{{< diagram >}}`, `{{< filesystem-diagram >}}`
5291

53-
## Page Frontmatter
92+
## Code Examples and Testing
5493

55-
Assist with creating appropriate frontmatter that includes:
94+
- Provide complete, working examples with proper testing annotations:
5695

57-
```yaml
58-
title: # Title of the page (h1)
59-
seotitle: # Page title for SEO
60-
list_title: # Title for article lists
61-
description: # Page description for SEO
62-
menu:
63-
product_version:
64-
weight: # Page sort order (follow level structure: 1-99, 101-199, etc.)
96+
```python
97+
print("Hello, world!")
6598
```
6699

67-
## Testing Code Blocks
100+
<!--pytest-codeblocks:expected-output-->
101+
102+
```
103+
Hello, world!
104+
```
68105
69-
When writing code examples, add appropriate testing annotations:
106+
- CLI command example:
70107
71-
```python
72-
print("Hello, world!")
108+
```sh
109+
influx query 'from(bucket:"example") |> range(start:-1h)'
73110
```
74111

75112
<!--pytest-codeblocks:expected-output-->
113+
76114
```
77-
Hello, world!
115+
Table: keys: [_start, _stop, _field, _measurement]
116+
_start:time _stop:time _field:string _measurement:string _time:time _value:float
117+
------------------------------ ------------------------------ ---------------------- ---------------------- ------------------------------ ----------------------------
78118
```
79119

80-
## InfluxDB-specific Conventions
120+
- Include necessary environment variables
121+
- Show proper credential handling for authenticated commands
81122

82-
- Use appropriate product names and versions consistently
83-
- Link to canonical documentation where appropriate
84-
- Follow InfluxData vocabulary and terminology guidelines
123+
## API Documentation
124+
125+
- Follow OpenAPI specification patterns
126+
- Match REST API examples to current implementation
127+
- Include complete request/response examples
128+
- Document required headers and authentication
129+
130+
## Versioning and Product Differentiation
131+
132+
- Clearly distinguish between different InfluxDB versions (1.x, 2.x, 3.x)
133+
- Use correct terminology for each product variant
134+
- Apply appropriate UI descriptions and screenshots
135+
- Reference appropriate query language per version
136+
137+
## Development Tools
138+
139+
- Vale.sh linter for style checking
140+
- Docker for local development and testing
141+
- pytest and pytest-codeblocks for validating code examples
142+
- Pre-commit hooks for quality assurance
85143

86-
## Pre-commit hooks
144+
## Related repositories
87145

88-
- Assist with Vale.sh linter configurations
89-
- Assist with Dockerfile and Docker Compose files
90-
- Assist with using pytest and pytest-codeblocks
146+
- **Internal dcumentation assistance requests**: https://github.com/influxdata/DAR/issues

0 commit comments

Comments
 (0)