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
|
||||
|
||||
Reference in New Issue
Block a user