b4l-project-template/ci/README.md

# /ci

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