forked from trent_larson/crowd-funder-for-time-pwa
feat(assets): standardize asset configuration with capacitor-assets
- Replace manual ImageMagick scripts with official capacitor-assets toolchain - Consolidate duplicate asset sources to single resources/ directory - Implement comprehensive asset configuration schema and validation - Add CI safeguards for asset validation and platform asset detection - Convert capacitor.config.json to TypeScript format - Pin Node.js version for deterministic builds - Remove legacy manual asset generation scripts: * generate-icons.sh, generate-ios-assets.sh, generate-android-icons.sh * check-android-resources.sh, check-ios-resources.sh * purge-generated-assets.sh - Add new asset management commands: * assets:config - generate/update configurations * assets:validate - validate configurations * assets:clean - clean generated assets (dev only) * build:native - build with asset generation - Create GitHub Actions workflow for asset validation - Update documentation with new asset management workflow This standardization eliminates asset duplication, improves build reliability, and provides a maintainable asset management system using Capacitor defaults. Breaking Changes: Manual asset generation scripts removed Migration: Assets now sourced from resources/ directory only CI: Automated validation prevents committed platform assets
This commit is contained in:
Matthew Raymer
214
doc/asset-migration-plan.md
Normal file
214
doc/asset-migration-plan.md
Normal file
@@ -0,0 +1,214 @@
|
||||
# TimeSafari Asset Configuration Migration Plan
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: 2025-08-14
|
||||
**Status**: 🎯 **IMPLEMENTATION** - Ready for Execution
|
||||
|
||||
## Overview
|
||||
|
||||
This document outlines the migration from the current mixed asset management
|
||||
system to a standardized, single-source asset configuration approach using
|
||||
`capacitor-assets` as the standard generator.
|
||||
|
||||
## Current State Analysis
|
||||
|
||||
### Asset Sources (Duplicated)
|
||||
|
||||
- **`assets/` directory**: Contains `icon.png`, `splash.png`, `splash_dark.png`
|
||||
- **`resources/` directory**: Contains identical files in platform-specific subdirectories
|
||||
- **Result**: Duplicate storage, confusion about source of truth
|
||||
|
||||
### Asset Generation (Manual)
|
||||
|
||||
- **Custom scripts**: `generate-icons.sh`, `generate-ios-assets.sh`, `generate-android-icons.sh`
|
||||
- **Bypass capacitor-assets**: Manual ImageMagick-based generation
|
||||
- **Inconsistent outputs**: Different generation methods for each platform
|
||||
|
||||
### Configuration (Scattered)
|
||||
|
||||
- **`capacitor-assets.config.json`**: Basic configuration at root
|
||||
- **Platform-specific configs**: Mixed in various build scripts
|
||||
- **No validation**: No schema or consistency checks
|
||||
|
||||
## Target State
|
||||
|
||||
### Single Source of Truth
|
||||
|
||||
- **`resources/` directory**: Capacitor default location for source assets
|
||||
- **Eliminate duplication**: Remove `assets/` directory after migration
|
||||
- **Standardized paths**: All tools read from `resources/`
|
||||
|
||||
### Standardized Generation
|
||||
|
||||
- **`capacitor-assets`**: Single tool for all platform asset generation
|
||||
- **Build-time generation**: Assets generated during build, not committed
|
||||
- **Deterministic outputs**: Same inputs → same outputs every time
|
||||
|
||||
### Centralized Configuration
|
||||
|
||||
- **`config/assets/`**: All asset-related configuration files
|
||||
- **Schema validation**: JSON schema for configuration validation
|
||||
- **CI safeguards**: Automated validation and compliance checks
|
||||
|
||||
## Migration Steps
|
||||
|
||||
### Phase 1: Foundation Setup ✅
|
||||
|
||||
- [x] Create `config/assets/` directory structure
|
||||
- [x] Create asset configuration schema (`schema.json`)
|
||||
- [x] Create enhanced capacitor-assets configuration
|
||||
- [x] Convert `capacitor.config.json` to `capacitor.config.ts`
|
||||
- [x] Pin Node.js version (`.nvmrc`, `.node-version`)
|
||||
- [x] Create dev-time asset configuration generator
|
||||
- [x] Create asset configuration validator
|
||||
- [x] Add npm scripts for asset management
|
||||
- [x] Update `.gitignore` with proper asset exclusions
|
||||
- [x] Create CI workflow for asset validation
|
||||
|
||||
### Phase 2: Validation & Testing
|
||||
|
||||
- [ ] Run `npm run assets:config` to generate new configuration
|
||||
- [ ] Run `npm run assets:validate` to verify configuration
|
||||
- [ ] Test `npm run build:native` workflow
|
||||
- [ ] Verify CI workflow passes all checks
|
||||
- [ ] Confirm no platform assets are committed to VCS
|
||||
|
||||
### Phase 3: Cleanup & Removal
|
||||
|
||||
- [ ] Remove `assets/` directory (after validation)
|
||||
- [ ] Remove manual asset generation scripts
|
||||
- [ ] Remove asset checking scripts
|
||||
- [ ] Update documentation references
|
||||
- [ ] Final validation of clean state
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### File Structure
|
||||
|
||||
```
|
||||
resources/ # Image sources ONLY
|
||||
icon.png
|
||||
splash.png
|
||||
splash_dark.png
|
||||
|
||||
config/assets/ # Versioned config & schema
|
||||
capacitor-assets.config.json
|
||||
schema.json
|
||||
|
||||
scripts/
|
||||
assets-config.js # Dev-time config generator
|
||||
assets-validator.js # Schema validator
|
||||
```
|
||||
|
||||
### Configuration Schema
|
||||
|
||||
The schema enforces:
|
||||
- Source files must be in `resources/` directory
|
||||
- Required fields for icon and splash sections
|
||||
- Android adaptive icon support (foreground/background/monochrome)
|
||||
- iOS LaunchScreen preferences
|
||||
- Target directory validation
|
||||
|
||||
### CI Safeguards
|
||||
|
||||
- **Schema validation**: Configuration must comply with schema
|
||||
- **Source file validation**: All referenced files must exist
|
||||
- **Platform asset denial**: Reject commits with generated assets
|
||||
- **Clean tree enforcement**: Build must not modify committed configs
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Local Validation
|
||||
|
||||
```bash
|
||||
# Generate configuration
|
||||
npm run assets:config
|
||||
|
||||
# Validate configuration
|
||||
npm run assets:validate
|
||||
|
||||
# Test build workflow
|
||||
npm run build:native
|
||||
|
||||
# Clean generated assets
|
||||
npm run assets:clean
|
||||
```
|
||||
|
||||
### CI Validation
|
||||
|
||||
- **Asset validation workflow**: Runs on asset-related changes
|
||||
- **Schema compliance**: Ensures configuration follows schema
|
||||
- **Source file existence**: Verifies all referenced files exist
|
||||
- **Platform asset detection**: Prevents committed generated assets
|
||||
- **Build tree verification**: Ensures clean tree after build
|
||||
|
||||
## Risk Mitigation
|
||||
|
||||
### Data Loss Prevention
|
||||
|
||||
- **Backup branch**: Create backup before removing `assets/`
|
||||
- **Validation checks**: Multiple validation steps before removal
|
||||
- **Gradual migration**: Phase-by-phase approach with rollback capability
|
||||
|
||||
### Build Continuity
|
||||
|
||||
- **Per-platform scripts unchanged**: All existing build orchestration preserved
|
||||
- **Standard toolchain**: Uses capacitor-assets, not custom scripts
|
||||
- **Fallback support**: Manual scripts remain until migration complete
|
||||
|
||||
### Configuration Consistency
|
||||
|
||||
- **Schema enforcement**: JSON schema prevents invalid configurations
|
||||
- **CI validation**: Automated checks catch configuration issues
|
||||
- **Documentation updates**: Clear guidance for future changes
|
||||
|
||||
## Success Criteria
|
||||
|
||||
### Technical Requirements
|
||||
|
||||
- [ ] Single source of truth in `resources/` directory
|
||||
- [ ] All platform assets generated via `capacitor-assets`
|
||||
- [ ] No manual asset generation scripts
|
||||
- [ ] Configuration validation passes all checks
|
||||
- [ ] CI workflow enforces asset policies
|
||||
|
||||
### Quality Metrics
|
||||
|
||||
- [ ] Zero duplicate asset sources
|
||||
- [ ] 100% configuration schema compliance
|
||||
- [ ] No platform assets committed to VCS
|
||||
- [ ] Clean build tree after asset generation
|
||||
- [ ] Deterministic asset outputs
|
||||
|
||||
### User Experience
|
||||
|
||||
- [ ] Clear asset management documentation
|
||||
- [ ] Simple development commands
|
||||
- [ ] Consistent asset generation across platforms
|
||||
- [ ] Reduced confusion about asset sources
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Execute Phase 2**: Run validation and testing steps
|
||||
2. **Verify CI workflow**: Ensure all checks pass
|
||||
3. **Execute Phase 3**: Remove duplicate assets and scripts
|
||||
4. **Update documentation**: Finalize README and BUILDING.md
|
||||
5. **Team training**: Ensure all developers understand new workflow
|
||||
|
||||
## Rollback Plan
|
||||
|
||||
If issues arise during migration:
|
||||
|
||||
1. **Restore backup branch**: `git checkout backup-before-asset-migration`
|
||||
2. **Revert configuration changes**: Remove new config files
|
||||
3. **Restore manual scripts**: Re-enable previous asset generation
|
||||
4. **Investigate issues**: Identify and resolve root causes
|
||||
5. **Plan revised migration**: Adjust approach based on lessons learned
|
||||
|
||||
---
|
||||
|
||||
**Status**: Ready for Phase 2 execution
|
||||
**Priority**: High
|
||||
**Estimated Effort**: 2-3 hours
|
||||
**Dependencies**: CI workflow validation
|
||||
**Stakeholders**: Development team
|
||||
Reference in New Issue
Block a user