Skip to content

Commit 365dce9

Browse files
EdwardAngertEdwardAngert
committed
feat: implement fully optimized documentation workflow architecture
- Complete streamlining of the documentation workflow system - Eliminate all duplication between workflow components - Create standardized presets for common validation scenarios - Add comprehensive documentation of the new architecture - Implement unified notification system with multiple channels - Optimize performance with conditional dependency installation - Enhance error reporting and user experience This implements the final optimization phase of the documentation workflow, creating a maintainable, extensible system with clear separation of concerns. All duplicate steps have been eliminated and responsibilities clearly defined.
1 parent 05727f2 commit 365dce9

File tree

4 files changed

+221
-125
lines changed

4 files changed

+221
-125
lines changed

‎.github/docs/OPTIMIZED-WORKFLOW.md

Lines changed: 183 additions & 105 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
1-
# Optimized Documentation Workflows
1+
# Optimized Documentation Workflow
22

3-
This document describes the optimized architecture for Coder's documentation workflows.
3+
This document explains the optimized documentation workflow architecture, which streamlines validation and preview processes for Coder's documentation.
44

55
## Architecture Overview
66

7+
The new architecture is designed with clear separation of concerns, improved error handling, and more efficient processing:
8+
79
```
810
┌─ Workflow Entry Points ─────────────────────────────────┐
911
│ │
@@ -17,7 +19,7 @@ This document describes the optimized architecture for Coder's documentation wor
1719
│ │
1820
│ docs-unified-optimized.yaml │
1921
│ - Configuration presets (PR, post-merge, weekly, CI) │
20-
│ - Standardized parameter handling │
22+
│ - Conditional dependency installation │
2123
│ - Single source of truth for all validation │
2224
│ │
2325
└───────────────────┬─────────────────────────────────────┘
@@ -34,136 +36,212 @@ This document describes the optimized architecture for Coder's documentation wor
3436
└──────────────────────────────────────────────────────────┘
3537
```
3638

37-
## Key Improvements
39+
## Key Components
40+
41+
### 1. Workflow Entry Points
42+
43+
- **docs-preview-optimized.yaml**: Quick previews for PR changes
44+
- **docs-link-check-optimized.yaml**: Post-merge validation focusing on link integrity
45+
- **weekly-docs-optimized.yaml**: Scheduled comprehensive checks
46+
- **[Future] docs-ci-optimized.yaml**: Fast syntax checking for CI processes
47+
48+
### 2. Unified Reusable Workflow
49+
50+
The `docs-unified-optimized.yaml` workflow serves as a central orchestration point:
51+
52+
- Provides standardized configuration presets
53+
- Conditionally installs needed dependencies
54+
- Maintains GitHub permissions and security settings
55+
- Orchestrates the execution of the core validation process
56+
57+
### 3. Core Implementation
58+
59+
The `docs-core/action.yaml` composite action:
60+
61+
- Phase 1: Security and Configuration
62+
- Validates environment security
63+
- Processes configuration presets
64+
- Determines tool requirements
65+
- Extracts context information
66+
67+
- Phase 2: File Detection
68+
- Robust file change detection with multiple fallback mechanisms
69+
- Direct Git integration for reliable diff generation
70+
- Handles multiple GitHub event contexts
71+
72+
- Phases 3-4: Validation
73+
- Flexible validation based on configuration
74+
- Independent validation steps that can run concurrently
75+
- Fault-tolerant execution that continues despite individual failures
76+
77+
- Phases 5-6: Results Processing
78+
- Unified results format across all validators
79+
- Multiple output formats for different consumers
80+
- Rich formatting with detailed guidance
3881

39-
1. **Consolidated Workflow Architecture:**
40-
- All workflows use the unified `docs-unified-optimized.yaml` workflow
41-
- Configuration is managed through standardized presets and parameter overrides
42-
43-
2. **Robust File Detection:**
44-
- Improved file detection with better error handling
45-
- Uses Git directly for more reliable detection of changed files
46-
- Intelligent fallbacks for different workflow contexts
47-
48-
3. **Unified Preview Generation:**
49-
- Single implementation of preview URL generation
50-
- Consistent handling of branch names
51-
- Direct links to changed files
52-
53-
4. **Separation of Concerns:**
54-
- Clear phases within the core implementation
55-
- Each workflow focuses on a specific use case
56-
- Presets provide consistent configurations
57-
58-
5. **Optimized Performance:**
59-
- Conditional dependency installation
60-
- Better caching
61-
- Parallel execution where possible
62-
63-
## Available Workflows
64-
65-
### 1. `docs-preview-optimized.yaml`
66-
- **Purpose:** Generate preview URLs for documentation changes in PRs
67-
- **Key Features:**
68-
- Fast execution with minimal validation
69-
- Rich PR comments with direct links
70-
- Helpful troubleshooting guidance
71-
72-
### 2. `docs-link-check-optimized.yaml`
73-
- **Purpose:** Post-merge validation of links and cross-references
74-
- **Key Features:**
75-
- Automatic GitHub issue creation
76-
- Slack notifications for failures
77-
- Comprehensive link checking
78-
79-
### 3. `weekly-docs-optimized.yaml`
80-
- **Purpose:** Weekly health check of all documentation
81-
- **Key Features:**
82-
- Scheduled execution
83-
- Stricter validation
84-
- Issue creation with specialized labels
82+
- Phases 7-8: Notification and Artifacts
83+
- Multi-channel notification support
84+
- Structured artifact storage
85+
- Comprehensive error reporting
8586

8687
## Configuration Presets
8788

88-
The unified workflow offers four standard presets:
89+
The workflow system includes standardized configuration presets for common scenarios:
90+
91+
### PR Preset
92+
93+
```yaml
94+
# For doc changes in PRs
95+
preset: 'pr'
96+
```
97+
98+
- Full validation with preview URLs
99+
- PR comments with direct links to changed files
100+
- Doesn't fail on validation errors
101+
102+
### Post-Merge Preset
103+
104+
```yaml
105+
# For recent changes to main branch
106+
preset: 'post-merge'
107+
```
108+
109+
- Focuses on link and cross-reference validation
110+
- Creates GitHub issues for broken links
111+
- No preview generation
112+
113+
### Weekly Preset
114+
115+
```yaml
116+
# For scheduled comprehensive checks
117+
preset: 'weekly'
118+
```
119+
120+
- Comprehensive link checking of all documentation
121+
- Strict validation with failure on errors
122+
- Creates GitHub issues with detailed diagnostics
123+
124+
### CI Preset
125+
126+
```yaml
127+
# For fast checks during CI
128+
preset: 'ci'
129+
```
130+
131+
- Rapid syntax and format checking
132+
- Minimal dependency requirements
133+
- Fails fast on errors
134+
135+
## Key Improvements
136+
137+
### 1. Elimination of Duplication
138+
139+
- Consolidated workflow architecture with single source of truth
140+
- Unified validation reporting and formatting
141+
- Centralized configuration management
142+
143+
### 2. Improved Error Handling
144+
145+
- Fault-tolerant file detection with multiple fallback mechanisms
146+
- Graceful degradation when steps fail
147+
- Detailed error reporting with fix guidance
89148
90-
1. **PR Preset (`pr`):**
91-
- Full validation with preview
92-
- Non-blocking errors
93-
- PR comment generation
149+
### 3. Optimized Performance
94150
95-
2. **Post-Merge Preset (`post-merge`):**
96-
- Focus on link checking
97-
- Issue creation
98-
- No preview or comment generation
151+
- Conditional dependency installation
152+
- Parallel validation where possible
153+
- Focused validation based on context
99154
100-
3. **Weekly Preset (`weekly`):**
101-
- Thorough link checking
102-
- Issue creation
103-
- Fails on errors for notifications
155+
### 4. Enhanced User Experience
104156
105-
4. **CI Preset (`ci`):**
106-
- Fast syntax and format validation
107-
- No link checking or preview
108-
- Fails on errors to block CI pipeline
157+
- Rich PR comments with direct links to documentation changes
158+
- Collapsible sections for detailed information
159+
- Multiple notification channels
160+
161+
### 5. Better Maintainability
162+
163+
- Clear separation of concerns between components
164+
- Standardized interfaces between stages
165+
- Comprehensive inline documentation
109166
110167
## Usage Examples
111168
112-
### Using the Unified Workflow Directly
169+
### Basic Usage with Preset
113170
114171
```yaml
115172
jobs:
116-
docs-validation:
173+
docs-check:
117174
uses: ./.github/workflows/docs-unified-optimized.yaml
118175
with:
119-
preset: 'pr' # Use a standard preset
120-
121-
# Optional overrides
122-
check-links: false # Disable link checking
123-
fail-on-error: true # Make errors blocking
176+
preset: 'pr'
124177
```
125178
126-
### Using the Presets with Customization
179+
### Using Preset with Overrides
127180
128181
```yaml
129182
jobs:
130-
custom-validation:
183+
docs-check:
131184
uses: ./.github/workflows/docs-unified-optimized.yaml
132185
with:
133-
preset: 'post-merge' # Start with post-merge preset
134-
135-
# Customize for this specific workflow
136-
check-cross-references: false # Disable cross-reference checking
137-
issue-labels: 'documentation,urgent' # Custom issue labels
186+
preset: 'pr'
187+
check-links: false # Skip link checking for faster results
188+
notification-channels: 'slack' # Add Slack notifications
138189
```
139190
140-
## Core Implementation Details
191+
### Full Custom Configuration
192+
193+
```yaml
194+
jobs:
195+
docs-check:
196+
uses: ./.github/workflows/docs-unified-optimized.yaml
197+
with:
198+
# Explicitly configure everything
199+
lint-markdown: true
200+
check-format: true
201+
check-links: true
202+
check-cross-references: true
203+
lint-vale: false
204+
generate-preview: true
205+
post-comment: true
206+
create-issues: false
207+
fail-on-error: false
208+
notification-channels: 'github-issue'
209+
issue-labels: 'documentation,urgent'
210+
```
211+
212+
## Troubleshooting
213+
214+
### Workflow Issues
215+
216+
1. **File Detection Failures**
217+
- The workflow now includes robust fallback mechanisms
218+
- Default files will be used for validation when detection fails
219+
- Check the workflow logs for notices about fallback usage
220+
221+
2. **Link Checking Errors**
222+
- Add false positives to `.github/docs/.lycheeignore`
223+
- Check if external services are temporarily unavailable
224+
- Look for changes to internal document structure
225+
226+
3. **Preview URL Issues**
227+
- Branch names with slashes will have slashes converted to dashes
228+
- Use the direct links provided in the PR comment
229+
- Check if the docs preview server is properly configured
141230

142-
The core implementation in `docs-core/action.yaml` provides:
231+
### Local Validation
143232

144-
1. **File Detection:**
145-
- Uses Git for reliable change detection
146-
- Falls back to alternative methods when Git diff fails
147-
- Handles different GitHub event contexts appropriately
233+
To run validation locally before creating a PR:
148234

149-
2. **Preview Generation:**
150-
- Consistent URL formatting
151-
- Direct links to changed files
152-
- Branch name sanitization
235+
```bash
236+
# Check markdown formatting
237+
pnpm exec markdownlint-cli2 docs/**/*.md
153238
154-
3. **Validation Steps:**
155-
- Markdown linting
156-
- Table format checking
157-
- Link validation
158-
- Cross-reference checking
159-
- Vale style validation
239+
# Check links (requires lychee installation)
240+
lychee docs/**/*.md
160241
161-
4. **Results Processing:**
162-
- Aggregated results in JSON format
163-
- Success rate calculation
164-
- Status badges
242+
# Format markdown tables
243+
make fmt/markdown
165244
166-
5. **PR Comment Management:**
167-
- Finding existing comments
168-
- Creating rich, helpful comments
169-
- Direct links to documentation changes
245+
# Check style with Vale
246+
vale --config=.github/docs/vale/.vale.ini docs/
247+
```

‎.github/workflows/docs-link-check-optimized.yaml

Lines changed: 13 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -30,19 +30,17 @@ jobs:
3030
issues: write
3131
with:
3232
preset: 'post-merge'
33-
# Additional customizations if needed
33+
# Configure notifications
34+
notification-channels: 'github-issue,slack'
3435
issue-labels: 'documentation,bug,needs-triage'
35-
36-
# Send Slack notification on failure during scheduled runs
37-
notify-slack:
38-
name: Send Notification
39-
needs: post-merge-validation
40-
if: failure() && github.event_name == 'schedule'
41-
runs-on: ubuntu-latest
42-
steps:
43-
- name: Send Slack notification
44-
run: |
45-
curl -X POST -H 'Content-type: application/json' -d '{"msg":"Documentation health check failed: Broken links or references found. Please check the GitHub issue that was created."}' ${{ secrets.DOCS_LINK_SLACK_WEBHOOK }}
46-
echo "Sent Slack notification"
47-
env:
48-
LOGS_URL: https://github.com/coder/coder/actions/runs/${{ github.run_id }}
36+
# Only check what matters after merge
37+
check-links: true
38+
check-cross-references: true
39+
lint-markdown: false
40+
check-format: false
41+
lint-vale: false
42+
generate-preview: false
43+
post-comment: false
44+
# Create issues but don't fail the workflow
45+
create-issues: true
46+
fail-on-error: false

‎.github/workflows/docs-preview-optimized.yaml

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,13 @@ jobs:
2222
pull-requests: write
2323
with:
2424
preset: 'pr' # Use the PR preset with all the right configurations
25-
# Override specific parameters if needed
26-
check-links: false # Faster preview by skipping link checking
27-
fail-on-error: false # Never fail for preview
25+
# Override specific parameters for faster preview
26+
check-links: false # Skip link checking for faster preview
27+
check-cross-references: true # Still check cross-references
28+
lint-markdown: true # Quick check for formatting
29+
check-format: true # Quick check for table formatting
30+
lint-vale: false # Skip style checking for faster preview
31+
generate-preview: true # Always generate preview
32+
post-comment: true # Always post comment
33+
fail-on-error: false # Never fail for preview
34+
notification-channels: '' # No external notifications

0 commit comments

Comments
 (0)