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

### Gitea Actions (Recommended)
This template is optimized for Gitea Actions. The workflow is already configured in `.gitea/workflows/auto-sort-files.yml`.

#### Required Setup:
1. **Enable Gitea Actions** on your Gitea instance
2. **Create CI Bot Token**:
   - Go to your Gitea user settings → Applications → Generate New Token
   - Name: `CI Auto-Sort Bot`
   - Scopes: `repo` (full repository access)
   - Copy the generated token
3. **Add Repository Secret**:
   - Go to your repository → Settings → Secrets
   - Add new secret: `CI_BOT_TOKEN`
   - Value: Paste the token from step 2
4. **Enable Actions**: Go to repository Settings → Actions → Enable Actions

#### Token Configuration:
The workflow uses `${{ secrets.CI_BOT_TOKEN }}` to authenticate git operations. This token must have:
- **Repository access**: Read and write permissions
- **Contents permission**: To commit and push changes
- **Actions permission**: To run workflows

#### Verification:
- Push a test file with DS_ or IMG_ prefix to verify the workflow runs
- Check the Actions tab in your repository for workflow execution logs
- Verify that files are automatically moved to correct directories

### GitHub Actions (Alternative)
If using GitHub instead of Gitea:
1. Copy `.gitea/workflows/auto-sort-files.yml` to `.github/workflows/`
2. Replace `CI_BOT_TOKEN` with `GITHUB_TOKEN` in the workflow
3. Update the push URL to use GitHub's format

### GitLab CI (Alternative)
To adapt for GitLab CI, create `.gitlab-ci.yml`:
```yaml
auto-sort:
  stage: organize
  script:
    - # Copy the bash script from .gitea/workflows/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