Skip to content

Commit 127a12d

Browse files
jstirnamanjstirnaman
authored
Merge branch 'master' into jts-feat-plugin-list
2 parents 31b4827 + 89739cd commit 127a12d

File tree

61 files changed

+6221
-1716
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

61 files changed

+6221
-1716
lines changed

‎.github/actions/report-broken-links/action.yml‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
name: 'Report Broken Links'
2+
description: 'Downloads broken link reports, generates PR comment, and posts results'
3+
4+
inputs:
5+
github-token:
6+
description: 'GitHub token for posting comments'
7+
required: false
8+
default: ${{ github.token }}
9+
max-links-per-file:
10+
description: 'Maximum links to show per file in comment'
11+
required: false
12+
default: '20'
13+
include-success-message:
14+
description: 'Include success message when no broken links found'
15+
required: false
16+
default: 'true'
17+
18+
outputs:
19+
has-broken-links:
20+
description: 'Whether broken links were found (true/false)'
21+
value: ${{ steps.generate-comment.outputs.has-broken-links }}
22+
broken-link-count:
23+
description: 'Number of broken links found'
24+
value: ${{ steps.generate-comment.outputs.broken-link-count }}
25+
26+
runs:
27+
using: 'composite'
28+
steps:
29+
- name: Download broken link reports
30+
uses: actions/download-artifact@v4
31+
with:
32+
path: reports
33+
continue-on-error: true
34+
35+
- name: Generate PR comment
36+
id: generate-comment
37+
run: |
38+
# Generate comment using our script
39+
node .github/scripts/comment-generator.js \
40+
--max-links ${{ inputs.max-links-per-file }} \
41+
${{ inputs.include-success-message == 'false' && '--no-success' || '' }} \
42+
--output-file comment.md \
43+
reports/ || echo "No reports found or errors occurred"
44+
45+
# Check if comment file was created and has content
46+
if [[ -f comment.md && -s comment.md ]]; then
47+
echo "comment-generated=true" >> $GITHUB_OUTPUT
48+
49+
# Count broken links by parsing the comment
50+
broken_count=$(grep -o "Found [0-9]* broken link" comment.md | grep -o "[0-9]*" || echo "0")
51+
echo "broken-link-count=$broken_count" >> $GITHUB_OUTPUT
52+
53+
# Check if there are actually broken links (not just a success comment)
54+
if [[ "$broken_count" -gt 0 ]]; then
55+
echo "has-broken-links=true" >> $GITHUB_OUTPUT
56+
else
57+
echo "has-broken-links=false" >> $GITHUB_OUTPUT
58+
fi
59+
else
60+
echo "has-broken-links=false" >> $GITHUB_OUTPUT
61+
echo "broken-link-count=0" >> $GITHUB_OUTPUT
62+
echo "comment-generated=false" >> $GITHUB_OUTPUT
63+
fi
64+
shell: bash
65+
66+
- name: Post PR comment
67+
if: steps.generate-comment.outputs.comment-generated == 'true'
68+
uses: actions/github-script@v7
69+
with:
70+
github-token: ${{ inputs.github-token }}
71+
script: |
72+
const fs = require('fs');
73+
74+
if (fs.existsSync('comment.md')) {
75+
const comment = fs.readFileSync('comment.md', 'utf8');
76+
77+
if (comment.trim()) {
78+
await github.rest.issues.createComment({
79+
issue_number: context.issue.number,
80+
owner: context.repo.owner,
81+
repo: context.repo.repo,
82+
body: comment
83+
});
84+
}
85+
}
86+
87+
- name: Report validation results
88+
run: |
89+
has_broken_links="${{ steps.generate-comment.outputs.has-broken-links }}"
90+
broken_count="${{ steps.generate-comment.outputs.broken-link-count }}"
91+
92+
if [ "$has_broken_links" = "true" ]; then
93+
echo "::error::❌ Link validation failed: Found $broken_count broken link(s)"
94+
echo "Check the PR comment for detailed broken link information"
95+
exit 1
96+
else
97+
echo "::notice::✅ Link validation passed successfully"
98+
echo "All links in the changed files are valid"
99+
if [ "${{ steps.generate-comment.outputs.comment-generated }}" = "true" ]; then
100+
echo "PR comment posted with validation summary and cache statistics"
101+
fi
102+
fi
103+
shell: bash

‎.github/actions/setup-docs-env/action.yml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
name: 'Setup Documentation Environment'
2+
description: 'Sets up Node.js environment and installs dependencies for documentation workflows'
3+
4+
runs:
5+
using: 'composite'
6+
steps:
7+
- name: Setup Node.js
8+
uses: actions/setup-node@v4
9+
with:
10+
node-version: '20'
11+
cache: 'yarn'
12+
13+
- name: Install dependencies
14+
run: yarn install
15+
shell: bash
16+
17+
- name: Verify Hugo installation
18+
run: |
19+
echo "Checking Hugo availability..."
20+
if command -v hugo &> /dev/null; then
21+
echo "✅ Hugo found on PATH: $(which hugo)"
22+
hugo version
23+
else
24+
echo "⚠️ Hugo not found on PATH, will use project-local Hugo via yarn"
25+
fi
26+
27+
echo "Checking yarn hugo command..."
28+
yarn hugo version || echo "⚠️ Project Hugo not available via yarn"
29+
shell: bash

‎.github/actions/validate-links/action.yml‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
name: 'Validate Links'
2+
description: 'Runs e2e browser-based link validation tests against Hugo site using Cypress'
3+
4+
inputs:
5+
files:
6+
description: 'Space-separated list of files to validate'
7+
required: true
8+
product-name:
9+
description: 'Product name for reporting (optional)'
10+
required: false
11+
default: ''
12+
cache-enabled:
13+
description: 'Enable link validation caching'
14+
required: false
15+
default: 'true'
16+
cache-key:
17+
description: 'Cache key prefix for this validation run'
18+
required: false
19+
default: 'link-validation'
20+
timeout:
21+
description: 'Test timeout in seconds'
22+
required: false
23+
default: '900'
24+
25+
outputs:
26+
failed:
27+
description: 'Whether validation failed (true/false)'
28+
value: ${{ steps.validate.outputs.failed }}
29+
30+
runs:
31+
using: 'composite'
32+
steps:
33+
- name: Restore link validation cache
34+
if: inputs.cache-enabled == 'true'
35+
uses: actions/cache@v4
36+
with:
37+
path: .cache/link-validation
38+
key: ${{ inputs.cache-key }}-${{ runner.os }}-${{ hashFiles('content/**/*.md', 'content/**/*.html') }}
39+
restore-keys: |
40+
${{ inputs.cache-key }}-${{ runner.os }}-
41+
${{ inputs.cache-key }}-
42+
43+
- name: Run link validation
44+
shell: bash
45+
run: |
46+
# Set CI-specific environment variables
47+
export CI=true
48+
export GITHUB_ACTIONS=true
49+
export NODE_OPTIONS="--max-old-space-size=4096"
50+
51+
# Set test runner timeout for Hugo shutdown
52+
export HUGO_SHUTDOWN_TIMEOUT=5000
53+
54+
# Add timeout to prevent hanging (timeout command syntax: timeout DURATION COMMAND)
55+
timeout ${{ inputs.timeout }}s node cypress/support/run-e2e-specs.js ${{ inputs.files }} \
56+
--spec cypress/e2e/content/article-links.cy.js || {
57+
exit_code=$?
58+
59+
# Handle timeout specifically
60+
if [ $exit_code -eq 124 ]; then
61+
echo "::error::Link validation timed out after ${{ inputs.timeout }} seconds"
62+
echo "::notice::This may indicate Hugo server startup issues or very slow link validation"
63+
else
64+
echo "::error::Link validation failed with exit code $exit_code"
65+
fi
66+
67+
# Check for specific error patterns and logs (but don't dump full content)
68+
if [ -f /tmp/hugo_server.log ]; then
69+
echo "Hugo server log available for debugging"
70+
fi
71+
72+
if [ -f hugo.log ]; then
73+
echo "Additional Hugo log available for debugging"
74+
fi
75+
76+
if [ -f /tmp/broken_links_report.json ]; then
77+
# Only show summary, not full report (full report is uploaded as artifact)
78+
broken_count=$(grep -o '"url":' /tmp/broken_links_report.json | wc -l || echo "0")
79+
echo "Broken links report contains $broken_count entries"
80+
fi
81+
82+
exit $exit_code
83+
}
84+
85+
# Report success if we get here
86+
echo "::notice::✅ Link validation completed successfully"
87+
echo "No broken links detected in the tested files"
88+
89+
- name: Upload logs on failure
90+
if: failure()
91+
uses: actions/upload-artifact@v4
92+
with:
93+
name: validation-logs-${{ inputs.product-name && inputs.product-name || 'default' }}
94+
path: |
95+
hugo.log
96+
/tmp/hugo_server.log
97+
if-no-files-found: ignore
98+
99+
100+
- name: Upload broken links report
101+
if: always()
102+
uses: actions/upload-artifact@v4
103+
with:
104+
name: broken-links-report${{ inputs.product-name && format('-{0}', inputs.product-name) || '' }}
105+
path: /tmp/broken_links_report.json
106+
if-no-files-found: ignore

‎.github/instructions/contributing.instructions.md‎

Lines changed: 16 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ Ready to contribute? Here's the essential workflow:
1818
2. [Fork and clone](#fork-and-clone-influxdata-documentation-repository) this repository
1919
3. [Install dependencies](#development-environment-setup) (Node.js, Yarn, Docker)
2020
4. Make your changes following [style guidelines](#making-changes)
21-
5. [Test your changes](#testing--quality-assurance) (pre-commit and pre-push hooks run automatically)
21+
5. [Test your changes](TESTING.md) (pre-commit and pre-push hooks run automatically)
2222
6. [Submit a pull request](#submission-process)
2323

2424
For detailed setup and reference information, see the sections below.
@@ -169,33 +169,30 @@ For more information about generating InfluxDB API documentation, see the
169169

170170
---
171171

172-
### Pre-commit Hooks
172+
## Testing & Quality Assurance
173173

174-
docs-v2 uses Lefthook to manage Git hooks that run during pre-commit and pre-push. The hooks run the scripts defined in `package.json` to lint Markdown and test code blocks.
175-
When you try to commit changes (`git commit`), Git runs
174+
For comprehensive testing information, including code block testing, link validation, style linting, and advanced testing procedures, see **[TESTING.md](TESTING.md)**.
176175

177-
#### Skip pre-commit hooks
176+
### Quick Testing Reference
178177

178+
```bash
179+
# Test code blocks
180+
yarn test:codeblocks:all
179181

180-
```sh
181-
git commit -m "<COMMIT_MESSAGE>" --no-verify
182-
```
183-
# ... (see full CONTRIBUTING.md for complete example)
184-
```python
185-
print("Hello, world!")
186-
```
182+
# Test links
183+
yarn test:links content/influxdb3/core/**/*.md
187184

188-
# ... (see full CONTRIBUTING.md for complete example)
189-
```sh
190-
docker compose run -T vale --config=content/influxdb/cloud-dedicated/.vale.ini --minAlertLevel=error content/influxdb/cloud-dedicated/write-data/**/*.md
185+
# Run style linting
186+
docker compose run -T vale content/**/*.md
191187
```
192188

189+
Pre-commit hooks run automatically when you commit changes, testing your staged files with Vale, Prettier, Cypress, and Pytest. To skip hooks if needed:
193190

194-
1. Install the [Vale VSCode](https://marketplace.visualstudio.com/items?itemName=ChrisChinchilla.vale-vscode) extension.
195-
2. In the extension settings, set the `Vale:Vale CLI:Path` value to `${workspaceFolder}/node_modules/.bin/vale`.
196-
191+
```sh
192+
git commit -m "<COMMIT_MESSAGE>" --no-verify
193+
```
197194

198-
_See full CONTRIBUTING.md for complete details._
195+
---
199196

200197
### Commit Guidelines
201198

@@ -229,10 +226,6 @@ _For the complete Complete Frontmatter Reference reference, see frontmatter-refe
229226

230227
_For the complete Complete Shortcodes Reference reference, see shortcodes-reference.instructions.md._
231228

232-
### Detailed Testing Setup
233-
234-
_For the complete Detailed Testing Setup reference, see testing-setup.instructions.md._
235-
236229
#### Vale style linting configuration
237230

238231
docs-v2 includes Vale writing style linter configurations to enforce documentation writing style rules, guidelines, branding, and vocabulary terms.

‎.github/instructions/shortcodes-reference.instructions.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1186,3 +1186,4 @@ Replace the following:
11861186
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: your [InfluxDB API token](/influxdb/v2/admin/tokens/)
11871187
```
11881188
1189+

0 commit comments

Comments
 (0)