Skip to content

Commit 8bfd0f2

Browse files
xiaoyu2erxiaoyu2er
committed
feat: update-docs-ci workflow
1 parent e9982b5 commit 8bfd0f2

File tree

9 files changed

+887
-164
lines changed

9 files changed

+887
-164
lines changed

‎.github/WORKFLOW_ENHANCEMENT_SUMMARY.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
# GitHub Actions Locale Workflow Enhancement - Summary
2+
3+
## 🎯 Task Completed: Extract Common Logic to Reusable, Testable Components
4+
5+
### What We Started With
6+
- GitHub Actions workflows with significant code duplication
7+
- Inline bash logic that was difficult to test locally
8+
- Hardcoded locale matrices and configurations
9+
- Manual workflow trigger issue where `branches` filter wasn't working correctly
10+
11+
### What We Accomplished
12+
13+
#### ✅ 1. Fixed Original GitHub Actions Trigger Issue
14+
- **Problem**: `branches` filter wasn't working for PRs from `docs/*` branches to `main`
15+
- **Solution**: Changed trigger to target `main` branch with `startsWith(github.head_ref, 'docs/')` condition for source branch filtering
16+
17+
#### ✅ 2. Created Reusable GitHub Action Component
18+
- **File**: `/.github/actions/check-locale-changes/action.yml`
19+
- **Features**:
20+
- Supports multiple trigger types: `manual`, `auto`, `docs-pr`
21+
- Dynamic locale detection from JSON configuration
22+
- Clean, modular design with proper inputs/outputs
23+
- Now uses external bash scripts instead of inline code
24+
25+
#### ✅ 3. Centralized Configuration Management
26+
- **File**: `/.github/locales-config.json`
27+
- **Features**:
28+
- Single source of truth for all locale configurations
29+
- Added `orama_private_api_key` field for all locales
30+
- Easy maintenance and updates
31+
32+
#### ✅ 4. Extracted Testable Bash Scripts
33+
34+
**Scripts Created:**
35+
1. **`generate-files-config.sh`** - Generates dynamic file patterns for change detection
36+
2. **`generate-locale-matrix.sh`** - Creates deployment matrix based on changes and trigger type
37+
3. **`test-locale-scripts.sh`** - Comprehensive test suite with 10 test scenarios
38+
39+
**Script Features:**
40+
- Comprehensive error handling and validation
41+
- Detailed logging and debugging capabilities
42+
- JSON validation and formatting
43+
- Support for all trigger scenarios
44+
- Modular, reusable functions
45+
46+
#### ✅ 5. Updated GitHub Action to Use Scripts
47+
- **Before**: 150+ lines of inline bash code
48+
- **After**: Clean, concise action that calls external scripts
49+
- **Benefits**:
50+
- Much easier to read and maintain
51+
- Logic can be tested locally
52+
- Scripts can be reused in other contexts
53+
- Better separation of concerns
54+
55+
#### ✅ 6. Comprehensive Testing Suite
56+
- **10 test scenarios** covering all trigger types and edge cases:
57+
- Files config generation
58+
- Manual triggers (all locales, specific locales)
59+
- Auto triggers (no changes, core changes, locale changes)
60+
- Docs PR triggers
61+
- Error handling (invalid triggers, missing parameters)
62+
- JSON validation
63+
64+
#### ✅ 7. Documentation and Maintenance
65+
- Created detailed README for the scripts directory
66+
- Inline documentation and comments in all scripts
67+
- Usage examples and integration guidelines
68+
69+
### Technical Improvements
70+
71+
#### Before Extraction:
72+
```yaml
73+
# Massive inline bash block with 100+ lines
74+
run: |
75+
locale_config=$(cat .github/locales-config.json)
76+
matrix_include="[]"
77+
# ... 100+ more lines of complex logic
78+
```
79+
80+
#### After Extraction:
81+
```yaml
82+
# Clean, simple action call
83+
run: |
84+
trigger_type="${{ inputs.trigger-type }}"
85+
manual_locales="${{ inputs.manual-locales }}"
86+
87+
if [ "$trigger_type" == "manual" ]; then
88+
output=$(.github/scripts/generate-locale-matrix.sh "$trigger_type" "$manual_locales")
89+
else
90+
changes_json='${{ toJSON(steps.changes.outputs) }}'
91+
output=$(.github/scripts/generate-locale-matrix.sh "$trigger_type" "" "$changes_json")
92+
fi
93+
94+
echo "$output" >> $GITHUB_OUTPUT
95+
```
96+
97+
### Local Testing Capabilities
98+
99+
You can now test the locale logic locally:
100+
101+
```bash
102+
# Test files config generation
103+
./.github/scripts/generate-files-config.sh
104+
105+
# Test manual deployment matrix
106+
./.github/scripts/generate-locale-matrix.sh manual "en,zh-hans"
107+
108+
# Test auto deployment with changes
109+
./.github/scripts/generate-locale-matrix.sh auto "" '{"core_any_changed": "true"}'
110+
111+
# Run comprehensive test suite
112+
./.github/scripts/test-locale-scripts.sh
113+
```
114+
115+
### Impact and Benefits
116+
117+
1. **Maintainability**: Centralized, modular components that are easier to update
118+
2. **Testability**: All logic can be tested locally without GitHub Actions
119+
3. **Reliability**: Comprehensive test coverage with automated validation
120+
4. **Reusability**: Scripts can be used in other workflows or contexts
121+
5. **Debugging**: Better logging and error messages for troubleshooting
122+
6. **Performance**: More efficient with proper error handling and validation
123+
124+
### Files Modified/Created
125+
126+
**Modified:**
127+
- `/.github/workflows/release.yml` - Uses reusable action
128+
- `/.github/workflows/update-docs-ci.yml` - Uses reusable action
129+
- `/.github/locales-config.json` - Added orama_private_api_key fields
130+
131+
**Created:**
132+
- `/.github/actions/check-locale-changes/action.yml` - Reusable action
133+
- `/.github/scripts/generate-files-config.sh` - Files config generator
134+
- `/.github/scripts/generate-locale-matrix.sh` - Matrix generator
135+
- `/.github/scripts/test-locale-scripts.sh` - Test suite
136+
- `/.github/scripts/README.md` - Documentation
137+
138+
### Validation
139+
140+
✅ All tests pass (10/10)
141+
✅ Scripts work correctly for all trigger types
142+
✅ JSON output is properly formatted and valid
143+
✅ Error handling works as expected
144+
✅ Workflows integrate successfully with the reusable action
145+
146+
The extraction is complete and the system is now much more maintainable, testable, and reliable! 🚀

‎.github/actions/check-locale-changes/action.yml‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
name: 'Check Locale Changes'
2+
description: 'Check which enabled locales have changes and generate deployment matrix'
3+
inputs:
4+
trigger-type:
5+
description: 'Type of trigger: "manual", "auto", or "docs-pr"'
6+
required: true
7+
manual-locales:
8+
description: 'Comma-separated list of locales for manual trigger (optional)'
9+
required: false
10+
default: ''
11+
outputs:
12+
matrix-include:
13+
description: 'JSON array of locales to deploy with their config'
14+
value: ${{ steps.generate-matrix.outputs.include }}
15+
has-changes:
16+
description: 'Whether any enabled locales have changes'
17+
value: ${{ steps.generate-matrix.outputs.has-changes }}
18+
19+
runs:
20+
using: 'composite'
21+
steps:
22+
- name: Generate dynamic files config (for auto/docs-pr triggers)
23+
if: inputs.trigger-type == 'auto' || inputs.trigger-type == 'docs-pr'
24+
id: generate-files-config
25+
shell: bash
26+
run: |
27+
# Use the dedicated script to generate files config
28+
files_yaml=$(.github/scripts/generate-files-config.sh)
29+
30+
echo "Generated files_yaml:"
31+
echo "$files_yaml"
32+
33+
# Save to output for next step
34+
{
35+
echo "files_yaml<<EOF"
36+
echo "$files_yaml"
37+
echo "EOF"
38+
} >> $GITHUB_OUTPUT
39+
40+
- name: Get changed files (for auto/docs-pr triggers)
41+
if: inputs.trigger-type == 'auto' || inputs.trigger-type == 'docs-pr'
42+
id: changes
43+
uses: tj-actions/changed-files@v41
44+
with:
45+
files_yaml: ${{ steps.generate-files-config.outputs.files_yaml }}
46+
47+
- name: Generate deployment matrix
48+
id: generate-matrix
49+
shell: bash
50+
run: |
51+
# Prepare arguments for the matrix generation script
52+
trigger_type="${{ inputs.trigger-type }}"
53+
manual_locales="${{ inputs.manual-locales }}"
54+
55+
if [ "$trigger_type" == "manual" ]; then
56+
# For manual trigger, we don't need changes JSON
57+
output=$(.github/scripts/generate-locale-matrix.sh "$trigger_type" "$manual_locales")
58+
else
59+
# For auto/docs-pr triggers, pass the changes JSON
60+
changes_json='${{ toJSON(steps.changes.outputs) }}'
61+
output=$(.github/scripts/generate-locale-matrix.sh "$trigger_type" "" "$changes_json")
62+
fi
63+
64+
# Parse the output (the script outputs two lines: include= and has-changes=)
65+
echo "$output" >> $GITHUB_OUTPUT

‎.github/locales-config.json‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,47 @@
11
{
22
"en": {
33
"secret_project_id": "VERCEL_PROJECT_EN_ID",
4+
"orama_private_api_key": "ORAMA_PRIVATE_API_KEY_EN",
45
"enabled": true
56
},
67
"zh-hans": {
78
"secret_project_id": "VERCEL_PROJECT_ZH_HANS_ID",
9+
"orama_private_api_key": "ORAMA_PRIVATE_API_KEY_ZH_HANS",
810
"enabled": true
911
},
1012
"zh-hant": {
1113
"secret_project_id": "VERCEL_PROJECT_ZH_HANT_ID",
14+
"orama_private_api_key": "ORAMA_PRIVATE_API_KEY_ZH_HANT",
1215
"enabled": true
1316
},
1417
"ar": {
1518
"secret_project_id": "VERCEL_PROJECT_AR_ID",
19+
"orama_private_api_key": "ORAMA_PRIVATE_API_KEY_AR",
1620
"enabled": true
1721
},
1822
"de": {
1923
"secret_project_id": "VERCEL_PROJECT_DE_ID",
24+
"orama_private_api_key": "ORAMA_PRIVATE_API_KEY_DE",
2025
"enabled": true
2126
},
2227
"es": {
2328
"secret_project_id": "VERCEL_PROJECT_ES_ID",
29+
"orama_private_api_key": "ORAMA_PRIVATE_API_KEY_ES",
2430
"enabled": true
2531
},
2632
"fr": {
2733
"secret_project_id": "VERCEL_PROJECT_FR_ID",
34+
"orama_private_api_key": "ORAMA_PRIVATE_API_KEY_FR",
2835
"enabled": true
2936
},
3037
"ja": {
3138
"secret_project_id": "VERCEL_PROJECT_JA_ID",
39+
"orama_private_api_key": "ORAMA_PRIVATE_API_KEY_JA",
3240
"enabled": true
3341
},
3442
"ru": {
3543
"secret_project_id": "VERCEL_PROJECT_RU_ID",
44+
"orama_private_api_key": "ORAMA_PRIVATE_API_KEY_RU",
3645
"enabled": true
3746
}
3847
}

‎.github/scripts/README.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# GitHub Locale Scripts
2+
3+
This directory contains reusable bash scripts for handling locale-based workflows in GitHub Actions.
4+
5+
## Scripts
6+
7+
### 1. `generate-files-config.sh`
8+
9+
Generates dynamic file configuration for the `changed-files` action based on the locales defined in `/.github/locales-config.json`.
10+
11+
**Usage:**
12+
```bash
13+
./generate-files-config.sh
14+
```
15+
16+
**Output:**
17+
YAML configuration for file pattern matching, with separate patterns for core files and each locale's content/messages.
18+
19+
---
20+
21+
### 2. `generate-locale-matrix.sh`
22+
23+
Generates deployment matrix for GitHub Actions based on locale changes and trigger type.
24+
25+
**Usage:**
26+
```bash
27+
# Manual trigger (all enabled locales)
28+
./generate-locale-matrix.sh manual
29+
30+
# Manual trigger (specific locales)
31+
./generate-locale-matrix.sh manual "en,zh-hans"
32+
33+
# Auto/docs-pr trigger (with changes JSON)
34+
./generate-locale-matrix.sh auto "" '{"core_any_changed": "true", "en_any_changed": "false"}'
35+
./generate-locale-matrix.sh docs-pr "" '{"core_any_changed": "true", "en_any_changed": "false"}'
36+
```
37+
38+
**Output:**
39+
- `include=<JSON array>` - Matrix of locales with their configuration
40+
- `has-changes=<boolean>` - Whether any changes were detected
41+
42+
---
43+
44+
### 3. `test-locale-scripts.sh`
45+
46+
Comprehensive test suite for validating all locale scripts functionality.
47+
48+
**Usage:**
49+
```bash
50+
./test-locale-scripts.sh
51+
```
52+
53+
**Features:**
54+
- Tests all trigger types and scenarios
55+
- Validates JSON output format
56+
- Tests error handling and edge cases
57+
- Provides detailed test reports
58+
59+
## Dependencies
60+
61+
- `jq` - JSON processing
62+
- Standard Unix utilities (`sed`, `tr`, `mktemp`)
63+
64+
## Configuration
65+
66+
Scripts read from `/.github/locales-config.json` which should contain:
67+
68+
```json
69+
{
70+
"locale": {
71+
"enabled": true,
72+
"secret_project_id": "VERCEL_PROJECT_LOCALE_ID",
73+
"orama_private_api_key": "ORAMA_PRIVATE_API_KEY_LOCALE"
74+
}
75+
}
76+
```
77+
78+
## Integration with GitHub Actions
79+
80+
These scripts are used by the reusable action `/.github/actions/check-locale-changes/action.yml` which:
81+
82+
1. Uses `generate-files-config.sh` to create dynamic file patterns
83+
2. Runs `changed-files` action with the generated patterns
84+
3. Uses `generate-locale-matrix.sh` to determine which locales to deploy
85+
4. Returns matrix configuration for downstream jobs
86+
87+
## Testing
88+
89+
Run the test suite regularly to ensure script functionality:
90+
91+
```bash
92+
# Make scripts executable
93+
chmod +x .github/scripts/*.sh
94+
95+
# Run comprehensive tests
96+
./.github/scripts/test-locale-scripts.sh
97+
```
98+
99+
The test suite validates:
100+
- Files config generation
101+
- Matrix generation for all trigger types
102+
- JSON output validity
103+
- Error handling
104+
- Edge cases and boundary conditions

0 commit comments

Comments
 (0)