Add CI auto-sort system for datasheets and images
- Add DS_ prefix for datasheets - automatically moved to docs/datasheets/ - Add IMG_ prefix for images - automatically moved to docs/images/ - Update FILE-NAMING-AND-VERSIONING.md with CI auto-sort prefix examples - Create comprehensive docs/datasheets/README.md with CI auto-sort documentation - Create comprehensive docs/images/README.md with CI auto-sort documentation - Add ci/auto-sort-files.yml GitHub Actions workflow for automatic file organization - Update ci/README.md with complete auto-sort system documentation - Update main README.md to reference CI auto-sort system - Enable users to upload files anywhere with correct prefix for automatic organization - Support multiple file types: PDF, DOC, PNG, JPG, SVG, etc. - Provide complete CI workflow with commit automation and error handling
This commit is contained in:
160
ci/README.md
160
ci/README.md
@@ -1,3 +1,161 @@
|
||||
# /ci
|
||||
|
||||
Continuous Integration configurations and automation scripts.
|
||||
Continuous Integration configuration and automation scripts.
|
||||
|
||||
## Purpose
|
||||
This directory contains CI/CD configuration files and automation scripts for the project, including automated file organization, testing, and deployment workflows.
|
||||
|
||||
## CI Workflows
|
||||
|
||||
### Auto-Sort Files (`auto-sort-files.yml`)
|
||||
Automatically organizes datasheets and images based on filename prefixes.
|
||||
|
||||
#### How It Works
|
||||
1. **Triggers**: Runs on push to main/develop branches and pull requests
|
||||
2. **Detection**: Scans the entire repository for files with specific prefixes
|
||||
3. **Organization**: Moves files to their correct directories
|
||||
4. **Commit**: Automatically commits the reorganized files
|
||||
|
||||
#### Supported Prefixes
|
||||
- **DS_**: Datasheets → moved to `docs/datasheets/`
|
||||
- **IMG_**: Images → moved to `docs/images/`
|
||||
|
||||
#### Example Usage
|
||||
```bash
|
||||
# User uploads files anywhere in the project:
|
||||
/some-folder/DS_STM32F401_datasheet_2024-08-11.pdf
|
||||
/random-location/IMG_pcb-layout_top-view_v1.0.0_2024-08-11.png
|
||||
|
||||
# CI automatically moves them to:
|
||||
docs/datasheets/DS_STM32F401_datasheet_2024-08-11.pdf
|
||||
docs/images/IMG_pcb-layout_top-view_v1.0.0_2024-08-11.png
|
||||
```
|
||||
|
||||
#### Supported File Types
|
||||
**Datasheets (DS_):**
|
||||
- PDF, DOC, DOCX, TXT
|
||||
|
||||
**Images (IMG_):**
|
||||
- PNG, JPG, JPEG, SVG, GIF, PDF, WEBP
|
||||
|
||||
#### Configuration
|
||||
The workflow can be customized by editing `auto-sort-files.yml`:
|
||||
- Add new file extensions
|
||||
- Modify destination directories
|
||||
- Add new prefix categories
|
||||
- Adjust trigger conditions
|
||||
|
||||
## Benefits of Auto-Sort System
|
||||
|
||||
### For Users
|
||||
- **No manual organization**: Upload files anywhere with correct prefix
|
||||
- **Consistent structure**: Files automatically end up in the right place
|
||||
- **Reduced errors**: No need to remember directory structures
|
||||
- **Time saving**: Focus on content, not file management
|
||||
|
||||
### For Teams
|
||||
- **Enforced standards**: Automatic compliance with naming conventions
|
||||
- **Reduced conflicts**: Files always in predictable locations
|
||||
- **Better collaboration**: Team members can find files easily
|
||||
- **Documentation quality**: Consistent organization improves documentation
|
||||
|
||||
### For Maintenance
|
||||
- **Automated cleanup**: Misplaced files are automatically corrected
|
||||
- **Audit trail**: Git history shows when files were moved
|
||||
- **Scalability**: Works regardless of project size
|
||||
- **Integration**: Works with existing workflows and tools
|
||||
|
||||
## Setup Instructions
|
||||
|
||||
### GitHub Actions
|
||||
1. The workflow file is already configured in `.github/workflows/` (copy from `ci/auto-sort-files.yml`)
|
||||
2. Ensure repository has appropriate permissions for the action to commit
|
||||
3. The workflow will run automatically on pushes and pull requests
|
||||
|
||||
### GitLab CI
|
||||
To adapt for GitLab CI, create `.gitlab-ci.yml`:
|
||||
```yaml
|
||||
auto-sort:
|
||||
stage: organize
|
||||
script:
|
||||
- # Copy the bash script from auto-sort-files.yml
|
||||
only:
|
||||
- main
|
||||
- develop
|
||||
```
|
||||
|
||||
### Other CI Systems
|
||||
The bash script in `auto-sort-files.yml` can be adapted for:
|
||||
- Jenkins
|
||||
- Azure DevOps
|
||||
- CircleCI
|
||||
- Travis CI
|
||||
- Any system that can run bash scripts
|
||||
|
||||
## Customization
|
||||
|
||||
### Adding New Prefixes
|
||||
To add new file type prefixes, modify the workflow:
|
||||
|
||||
```bash
|
||||
# Example: Add CAD files with CAD_ prefix
|
||||
find . -name "CAD_*.step" -o -name "CAD_*.sldprt" | while read file; do
|
||||
if [[ "$file" != ./mechanical/cad/* ]]; then
|
||||
filename=$(basename "$file")
|
||||
move_file "$file" "mechanical/cad/$filename"
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
### Subdirectory Organization
|
||||
For more sophisticated organization, add logic to sort into subdirectories:
|
||||
|
||||
```bash
|
||||
# Example: Sort datasheets by component type
|
||||
case "$filename" in
|
||||
DS_STM32*|DS_ESP32*) dest_dir="docs/datasheets/microcontrollers/" ;;
|
||||
DS_LM*|DS_AMS*) dest_dir="docs/datasheets/power-management/" ;;
|
||||
*) dest_dir="docs/datasheets/" ;;
|
||||
esac
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### File Naming
|
||||
- Always use the correct prefix (DS_, IMG_)
|
||||
- Follow the established naming convention
|
||||
- Include version numbers and dates
|
||||
- Use descriptive filenames
|
||||
|
||||
### Repository Management
|
||||
- Review auto-sort commits regularly
|
||||
- Manually organize files into subdirectories as needed
|
||||
- Keep the CI workflow updated with project needs
|
||||
- Monitor for any files that might be missed
|
||||
|
||||
### Team Guidelines
|
||||
- Train team members on prefix usage
|
||||
- Document any custom prefixes or rules
|
||||
- Include prefix requirements in contribution guidelines
|
||||
- Set up notifications for auto-sort commits
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
1. **Files not moving**: Check filename prefix and extension
|
||||
2. **Permission errors**: Ensure CI has write access to repository
|
||||
3. **Workflow not running**: Check trigger conditions and branch names
|
||||
4. **Duplicate files**: CI will not overwrite existing files
|
||||
|
||||
### Debugging
|
||||
- Check workflow logs in CI system
|
||||
- Verify file extensions are supported
|
||||
- Ensure files are not already in correct location
|
||||
- Test bash script locally before deploying
|
||||
|
||||
## Future Enhancements
|
||||
- Add support for more file types
|
||||
- Implement smart subdirectory sorting
|
||||
- Add file validation and quality checks
|
||||
- Integration with project management tools
|
||||
- Automated file naming compliance checking
|
||||
|
||||
113
ci/auto-sort-files.yml
Normal file
113
ci/auto-sort-files.yml
Normal file
@@ -0,0 +1,113 @@
|
||||
# CI Auto-Sort Configuration for Datasheets and Images
|
||||
# This GitHub Actions workflow automatically moves files with specific prefixes to their correct directories
|
||||
|
||||
name: Auto-Sort Files
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [ main, develop ]
|
||||
pull_request:
|
||||
branches: [ main ]
|
||||
|
||||
jobs:
|
||||
auto-sort:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
token: ${{ secrets.GITHUB_TOKEN }}
|
||||
|
||||
- name: Auto-sort datasheets and images
|
||||
run: |
|
||||
#!/bin/bash
|
||||
set -e
|
||||
|
||||
# Flag to track if any files were moved
|
||||
FILES_MOVED=false
|
||||
|
||||
# Function to move files with logging
|
||||
move_file() {
|
||||
local src="$1"
|
||||
local dest="$2"
|
||||
local dest_dir=$(dirname "$dest")
|
||||
|
||||
# Create destination directory if it doesn't exist
|
||||
mkdir -p "$dest_dir"
|
||||
|
||||
# Move file if it's not already in the correct location
|
||||
if [ "$src" != "$dest" ] && [ -f "$src" ]; then
|
||||
echo "Moving: $src -> $dest"
|
||||
mv "$src" "$dest"
|
||||
FILES_MOVED=true
|
||||
fi
|
||||
}
|
||||
|
||||
# Find and move datasheet files (DS_ prefix)
|
||||
echo "Searching for datasheet files with DS_ prefix..."
|
||||
find . -name "DS_*.pdf" -o -name "DS_*.doc" -o -name "DS_*.docx" -o -name "DS_*.txt" | while read file; do
|
||||
# Skip files already in docs/datasheets/
|
||||
if [[ "$file" != ./docs/datasheets/* ]]; then
|
||||
filename=$(basename "$file")
|
||||
move_file "$file" "docs/datasheets/$filename"
|
||||
fi
|
||||
done
|
||||
|
||||
# Find and move image files (IMG_ prefix)
|
||||
echo "Searching for image files with IMG_ prefix..."
|
||||
find . -name "IMG_*.png" -o -name "IMG_*.jpg" -o -name "IMG_*.jpeg" -o -name "IMG_*.svg" -o -name "IMG_*.gif" -o -name "IMG_*.pdf" -o -name "IMG_*.webp" | while read file; do
|
||||
# Skip files already in docs/images/
|
||||
if [[ "$file" != ./docs/images/* ]]; then
|
||||
filename=$(basename "$file")
|
||||
move_file "$file" "docs/images/$filename"
|
||||
fi
|
||||
done
|
||||
|
||||
# Check if any files were moved
|
||||
if [ "$FILES_MOVED" = true ]; then
|
||||
echo "Files were moved. Setting output for commit step."
|
||||
echo "files_moved=true" >> $GITHUB_OUTPUT
|
||||
else
|
||||
echo "No files needed to be moved."
|
||||
echo "files_moved=false" >> $GITHUB_OUTPUT
|
||||
fi
|
||||
id: sort_files
|
||||
|
||||
- name: Commit moved files
|
||||
if: steps.sort_files.outputs.files_moved == 'true'
|
||||
run: |
|
||||
git config --local user.email "action@github.com"
|
||||
git config --local user.name "GitHub Action Auto-Sort"
|
||||
git add docs/datasheets/ docs/images/
|
||||
git commit -m "Auto-sort: Move DS_ and IMG_ prefixed files to correct directories
|
||||
|
||||
- Moved datasheet files (DS_*) to docs/datasheets/
|
||||
- Moved image files (IMG_*) to docs/images/
|
||||
- Automated by CI auto-sort workflow"
|
||||
|
||||
- name: Push changes
|
||||
if: steps.sort_files.outputs.files_moved == 'true'
|
||||
uses: ad-m/github-push-action@master
|
||||
with:
|
||||
github_token: ${{ secrets.GITHUB_TOKEN }}
|
||||
branch: ${{ github.ref }}
|
||||
|
||||
- name: Create summary
|
||||
run: |
|
||||
echo "## Auto-Sort Results" >> $GITHUB_STEP_SUMMARY
|
||||
echo "" >> $GITHUB_STEP_SUMMARY
|
||||
if [ "${{ steps.sort_files.outputs.files_moved }}" = "true" ]; then
|
||||
echo "✅ Files were automatically moved to correct directories" >> $GITHUB_STEP_SUMMARY
|
||||
echo "" >> $GITHUB_STEP_SUMMARY
|
||||
echo "### Moved Files:" >> $GITHUB_STEP_SUMMARY
|
||||
echo "- Datasheet files (DS_*) → docs/datasheets/" >> $GITHUB_STEP_SUMMARY
|
||||
echo "- Image files (IMG_*) → docs/images/" >> $GITHUB_STEP_SUMMARY
|
||||
else
|
||||
echo "ℹ️ No files needed to be moved - all files are properly organized" >> $GITHUB_STEP_SUMMARY
|
||||
fi
|
||||
echo "" >> $GITHUB_STEP_SUMMARY
|
||||
echo "### Supported Prefixes:" >> $GITHUB_STEP_SUMMARY
|
||||
echo "- **DS_**: Datasheets (PDF, DOC, DOCX, TXT)" >> $GITHUB_STEP_SUMMARY
|
||||
echo "- **IMG_**: Images (PNG, JPG, SVG, GIF, PDF, WEBP)" >> $GITHUB_STEP_SUMMARY
|
||||
Reference in New Issue
Block a user