You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
enhance: optimize workflow with unified reporting and concurrency
- Add unified results aggregation and reporting
- Organize workflow into clear phases for concurrent execution
- Enhance docs-shared action with better dependency structure
- Update post-merge checks to include cross-reference validation
- Remove Slack notification in favor of GitHub issues
- Improve README with updated architecture documentation
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
-`vale`: Configuration and style rules for Vale documentation linting
10
10
-`.linkspector.yml`: Configuration for link checking
11
11
12
12
## Available Workflows
13
13
14
14
### Reusable Workflow
15
15
16
-
The `docs-unified.yaml` workflow provides a reusable workflow that can be called from other workflows. This combines all documentation checks in one workflow:
16
+
The `docs-unified.yaml` workflow provides a reusable workflow that can be called from other workflows. This combines all documentation checks in one workflow with optimized concurrent execution:
17
17
18
18
```yaml
19
19
jobs:
@@ -54,6 +54,70 @@ The `docs-link-check.yaml` workflow runs after merges to main and on a weekly sc
54
54
7. **PR Comments**: Creates or updates PR comments with preview links and validation results
55
55
8. **Post-Merge Validation**: Ensures documentation quality after merges to main
56
56
9. **Issue Creation**: Automatically creates GitHub issues for broken links
57
+
10. **Optimized Concurrent Execution**: Phases-based structure for parallel validation
58
+
11. **Unified Result Reporting**: Aggregates results from all validators into a single JSON structure
59
+
60
+
## Workflow Architecture
61
+
62
+
The documentation workflow is designed for maximum efficiency using a phase-based approach:
63
+
64
+
### Phase 1: Setup and Environment Validation
65
+
- Security configuration
66
+
- Directory validation
67
+
- Environment setup (Node.js, PNPM, Vale)
68
+
69
+
### Phase 2: File Analysis
70
+
- Identify changed documentation files
71
+
- Parse files into different formats for processing
72
+
- Check for manifest.json changes
73
+
74
+
### Phase 3: Concurrent Validation
75
+
- All validation steps run in parallel:
76
+
- Markdown linting
77
+
- Table formatting validation
78
+
- Link checking
79
+
- Vale style checking
80
+
- Cross-reference validation
81
+
82
+
### Phase 4: Preview Generation
83
+
- Generate preview URLs for documentation changes
84
+
- Build links to new documentation
85
+
86
+
### Phase 5: Results Aggregation
87
+
- Collect results from all validation steps
88
+
- Normalize into a unified JSON structure
89
+
- Calculate success metrics and statistics
90
+
- Generate summary badge
91
+
92
+
### Phase 6: PR Comment Management
93
+
- Find existing comments or create new ones
94
+
- Format results in a user-friendly way
95
+
- Provide actionable guidance for fixing issues
96
+
97
+
## Unified Results Reporting
98
+
99
+
The workflow now aggregates all validation results into a single JSON structure:
100
+
101
+
```json
102
+
[
103
+
{
104
+
"name": "markdown-lint",
105
+
"status": "success|failure",
106
+
"output": "Raw output from the validation tool",
107
+
"guidance": "Human-readable guidance on how to fix",
108
+
"fix_command": "Command to run to fix the issue"
109
+
},
110
+
// Additional validation results...
111
+
]
112
+
```
113
+
114
+
### Benefits of Unified Reporting:
115
+
116
+
1. **Consistency**: All validation tools report through the same structure
117
+
2. **Integration**: JSON output can be easily consumed by other tools or dashboards
118
+
3. **Statistics**: Automatic calculation of pass/fail rates and success percentages
119
+
4. **Diagnostics**: All validation results in one place for easier debugging
120
+
5. **Extensibility**: New validators can be added with the same reporting format
57
121
58
122
## Formatting Local Workflow
59
123
@@ -67,4 +131,9 @@ The GitHub Actions workflow only checks formatting and reports issues but doesn'
67
131
68
132
## Examples
69
133
70
-
See the `docs-reusable-example.yaml` workflow for a complete example that demonstrates both the reusable workflow and direct action usage.
134
+
See the `docs-reusable-example.yaml` workflow for a complete example that demonstrates both the reusable workflow and direct action usage with:
0 commit comments