2d17bfd3b4
- Update BUILDING.md with current build system information - Modernize various README files across the project - Update CHANGELOG.md with recent changes - Improve documentation consistency and formatting - Update platform-specific documentation (iOS, Electron, Docker) - Enhance test documentation and build guides
216 lines
6.7 KiB
Markdown
216 lines
6.7 KiB
Markdown
# 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
|