Skip to content

WORKFLOW_IMPROVEMENT.md

Latest commit

 

History

History
150 lines (116 loc) · 5.34 KB

WORKFLOW_IMPROVEMENT.md

File metadata and controls

150 lines (116 loc) · 5.34 KB

GitHub Action Workflow Improvement

Overview

The GitHub Action workflow has been improved to use the local update-version.sh script instead of complex inline bash commands. This change provides significant benefits in terms of maintainability, consistency, and reliability.

Before vs After

Before (Complex Inline Commands)

- name: Update version information
  run: |
    VERSION="${{ steps.version.outputs.version }}"
    DATE="${{ steps.version.outputs.date }}"
    
    # Function to update downloadContent.json
    update_download_content() {
      local file_path=$1
      echo "Updating $file_path"
      
      # Update the description text
      sed -i "s/GeoDa [0-9]\+\.[0-9]\+\.[0-9]\+\.[0-9]\+ with new features/GeoDa $VERSION with new features/g" "$file_path"
      
      # Add new release entry at the beginning of releases array
      awk -v version="$VERSION" -v date="$DATE" '
      /"releases": \[/ {
        print $0
        print "      { \"date\": \"" date "\", \"version\": \"" version "\" },"
        next
      }
      { print }
      ' "$file_path" > "${file_path}.tmp" && mv "${file_path}.tmp" "$file_path"
    }
    
    # ... 50+ more lines of complex bash functions ...

After (Clean Script Call)

- name: Update version information
  run: |
    VERSION="${{ steps.version.outputs.version }}"
    DATE="${{ steps.version.outputs.date }}"
    
    echo "Updating version to: $VERSION"
    echo "Using date: $DATE"
    
    # Run the version update script
    ./update-version.sh "$VERSION" "$DATE"

Benefits

1. Maintainability

  • Single source of truth: All update logic is in one place (scripts/update-version.js)
  • Easier debugging: Issues can be reproduced locally
  • Cleaner workflow: GitHub Action focuses on orchestration, not implementation
  • Reduced complexity: No complex inline bash functions

2. Consistency

  • Same logic: GitHub Action and local testing use identical code
  • Same validation: Both environments use the same validation rules
  • Same error handling: Consistent error messages and recovery procedures
  • Same backup strategy: Automatic backups in both environments

3. Reliability

  • Tested locally: Script can be thoroughly tested before deployment
  • Better error handling: More robust error detection and reporting
  • Automatic backups: Files are backed up before changes
  • Validation: JSON validation ensures file integrity

4. Development Workflow

  • Local testing: Developers can test changes locally before pushing
  • Iterative development: Easy to modify and test the update logic
  • Version control: Script changes are tracked in git
  • Code review: Script changes can be reviewed separately from workflow changes

5. Debugging

  • Local reproduction: Issues can be reproduced and debugged locally
  • Better logging: More detailed progress and error reporting
  • Step-by-step execution: Can run individual parts of the script
  • Dry run mode: Test changes without making them

Technical Details

Workflow Structure

jobs:
  update-version:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout repository
      uses: actions/checkout@v4
      
    - name: Setup Node.js
      uses: actions/setup-node@v4
      
    - name: Extract version from tag
      id: version
      run: |
        VERSION=${GITHUB_REF#refs/tags/v}
        DATE=$(date +'%-m/%-d/%Y')
        
    - name: Update version information
      run: |
        ./update-version.sh "$VERSION" "$DATE"
        
    - name: Validate JSON files
      run: |
        node scripts/validate-json.js "$VERSION"
        
    - name: Create Pull Request
      uses: peter-evans/create-pull-request@v5

Script Dependencies

  • Node.js: Required for the update script (already included in Ubuntu runner)
  • Bash: Required for the wrapper script (already included in Ubuntu runner)
  • No additional tools: No need for jq or other external dependencies

Migration Benefits

For Developers

  • Easier contribution: New developers can understand and modify the script
  • Local development: Test changes without pushing to GitHub
  • Better tooling: Can use IDE features for debugging and development

For Operations

  • Reduced maintenance: Less complex workflow to maintain
  • Better monitoring: Clearer logs and error messages
  • Easier troubleshooting: Issues can be reproduced locally

For Quality Assurance

  • Consistent testing: Same logic used in all environments
  • Better validation: More comprehensive error checking
  • Automatic backups: Safety net for all operations

Future Enhancements

With this architecture, future improvements become much easier:

  1. Additional file types: Can be added to the script without workflow changes
  2. New validation rules: Can be implemented in the validation script
  3. Custom date formats: Can be added as script options
  4. Email notifications: Can be added to the script
  5. Web interface: Could be built on top of the script

Conclusion

This improvement transforms the GitHub Action from a complex, hard-to-maintain workflow into a clean, orchestration layer that leverages well-tested, maintainable scripts. The benefits in terms of development efficiency, reliability, and maintainability make this a significant improvement to the version update process.