MVP Repository Upgrade Initiative

[rmenner]

TRD: MVP Repository Upgrade Initiative

Executive Summary

This document outlines the technical requirements for upgrading 30 repositories to a standardized development toolchain and workflow. The initiative aims to modernize our development infrastructure by implementing centralized CI/CD workflows, standardized build tools, and improved linting systems across all Auro repositories.

Project Scope:

• 30 repositories to be upgraded
• Estimated effort: ~70 hours (2+ hours per repository plus compliance infrastructure)
• Timeline: 1-2 sprints depending on team collaboration

Project Overview

Objectives

1. Standardization: Implement consistent tooling and workflows across all repositories
2. Centralization: Reduce duplication by creating reusable CI/CD workflows
3. Modernization: Upgrade to modern development tools (Biome, auro-cli)
4. Efficiency: Streamline development and release processes

Key Components

• Centralized CI/CD: Reusable GitHub Actions workflows in auro-actions repository
• Modern Linting: Migration from ESLint/Prettier to Biome with lint-staged
• Standardized Build Tools: Implementation of auro-cli across all repositories
• Package Modernization: Updated module exports and release configurations

Technical Requirements

Prerequisites

Critical Path: Task 0 must be completed before any repository upgrades can begin.

Task Dependencies

Task 0 (Global) → Tasks 1-3 (Per Repo) → Tasks 4-7 (Interdependent Group) → Task 8 (Global Monitoring)

Important: Tasks 4-7 are tightly coupled and must be completed as a cohesive unit. They cannot be implemented independently due to cross-dependencies in the build system, module structure, and configuration files. Task 8 requires completion of all previous tasks to establish the baseline for compliance monitoring.

---

Detailed Task Specifications

Phase 1: Infrastructure Setup

Task 0: Create Unified CI/CD Repository (auro-actions)

Scope: Global (execute once)

Effort: 2 days

Objective: Establish centralized repository for reusable GitHub Actions workflows and composite actions.

Technical Requirements:

• Create new auro-actions repository in organization
• Migrate and convert existing workflows from auro-slideshow to reusable format
• Implement input parameters for repository-specific configuration
• Establish proper versioning and release strategy

Deliverables:

• New auro-actions repository created
• All workflows converted to reusable format
• Custom actions migrated and documented
• Input/output specifications defined
• Basic documentation for consumption
• Initial release (v1.0.0) tagged
• Integration testing with auro-slideshow

Success Criteria:

• Workflows function correctly when consumed externally
• No functionality regression from original implementations
• Documentation enables smooth adoption

Reference: https://github.com/AlaskaAirlines/auro-slideshow/tree/dev/.github

---

Phase 2: Repository Configuration

Task 1: Repository Setup and Branch Configuration

Scope: Per repository (30 repositories)

Objective: Configure repository settings for new development workflow.

Technical Requirements:

• Implement dev branch as new default branch
• Apply consistent branch protection rules
• Update repository secrets for new workflow

Deliverables:

• dev branch created from current default and set as new default
• Branch protection rules imported from auro-slideshow template
• NPM_TOKEN secret updated with current value
• Configuration verification completed

Success Criteria:

• Branch protection prevents direct pushes to protected branches
• Required status checks function correctly
• Secrets are properly configured for CI/CD

---

Task 2: Workflow Migration

Scope: Per repository (30 repositories)

Objective: Replace repository-specific workflows with calls to centralized reusable workflows.

Technical Requirements:

• Replace existing GitHub Actions workflows
• Configure repository-specific inputs
• Update branch triggers for new workflow

Dependencies: Task 0 (auro-actions repository)

Deliverables:

• Existing workflows replaced with auro-actions calls
• Workflow triggers updated to use dev branch
• Repository-specific inputs configured
• Secrets and variables properly mapped
• Workflow execution testing completed
• Obsolete workflow files removed

Success Criteria:

• All workflows execute successfully with new configuration
• No loss of existing functionality
• Consistent behavior across all repositories

---

Task 3: Linting System Modernization

Scope: Per repository (30 repositories)

Objective: Replace ESLint/Prettier with Biome and implement efficient pre-commit workflows.

Technical Requirements:

• Remove legacy linting dependencies and configurations
• Install and configure Biome with centralized settings
• Implement Husky pre-commit hooks with lint-staged

Dependencies: auro-config repository must contain Biome configuration

Deliverables:

• ESLint and Prettier dependencies removed
• Biome and lint-staged installed as dev dependencies
• auro-config Biome settings imported
• NPM scripts added for linting and formatting
• Husky updated and pre-commit hooks configured
• lint-staged configured for staged files only
• Commit message linting updated (if applicable)
• End-to-end testing of linting workflow
• Documentation updated for new workflow

Success Criteria:

• Linting performance improved (Biome is faster than ESLint)
• Pre-commit hooks prevent problematic code from being committed
• Consistent code style across all repositories

---

Phase 3: Build System Modernization

Critical: Tasks 4-7 form an interdependent group and must be completed together.

Task 4: Build Tool Standardization (auro-cli Integration)

Scope: Per repository (30 repositories)

Objective: Implement standardized build, test, and development tools across all repositories.

Technical Requirements:

• Install auro-cli as primary build tool
• Update test infrastructure for new module structure
• Fix import paths and SCSS compilation

Deliverables:

• auro-cli installed as development dependency
• Conflicting build tools removed
• Package.json scripts updated for auro-cli commands
• Build/test command functionality verified
• Test file import statements updated
• Module structure compatibility ensured
• Test utilities imports fixed
• Test configuration updated as needed
• Test suite execution verified
• SCSS import paths updated for new structure
• Style dependency resolution verified
• Style compilation testing completed
• Style reference validation completed
• Test documentation updated

Files Modified:

• package.json
• test/**/*.test.js
• src/**/*.js
• Test configuration files

Success Criteria:

• All tests pass with new build system
• No broken imports or style references
• Build performance maintained or improved

---

Task 5: Demo and Documentation Updates

Scope: Per repository (30 repositories)

Objective: Ensure demo files and documentation work with new build system.

Dependencies: Task 4 (auro-cli installation)

Deliverables:

• Demo file import paths updated
• Demo compatibility with auro-cli dev command verified
• Demo page identification middleware tested
• Demo build process validation completed
• Demo configuration updated as needed
• Documentation processing verified

Files Modified:

• demo/**/*.js
• demo/**/*.html
• Documentation files
• Demo configuration files

Success Criteria:

• Demo pages render correctly with new build system
• Documentation builds without errors
• Developer experience maintained or improved

---

Task 6: Package Structure and Release Configuration

Scope: Per repository (30 repositories)

Objective: Implement modern package exports and automated release management.

Dependencies: Task 4 (auro-cli installation)

Technical Requirements:

• Create modern ES module entry points
• Configure package exports for multiple consumption patterns
• Implement automated release configuration

Deliverables:

• index.js created with proper ES module exports
• registered.js created for automatic component registration
• Package.json "exports" field added
• Component, styles, and utilities exports configured
• Backward compatibility maintained
• CommonJS and ES module support verified
• .releaserc file created with proper configuration
• Release configuration removed from package.json
• Import testing in various environments completed
• Release configuration functionality verified
• Version bumping and changelog generation tested
• JSDoc documentation added
• Import options and release process documentation updated

Files Created:

• index.js
• registered.js
• .releaserc

Files Modified:

• package.json

Success Criteria:

• Packages can be imported using modern import syntax
• Automatic component registration works correctly
• Release process is fully automated

---

Task 7: Configuration Cleanup

Scope: Per repository (30 repositories)

Objective: Remove obsolete configuration files and clean up repository structure.

Dependencies: Task 4 (auro-cli installation)

Deliverables:

• .npmignore removed (if package.json files field used)
• Old linting configuration files removed
• Obsolete build configuration files removed
• File removal impact assessment completed
• Package publishing functionality verified

Files Removed:

• .npmignore (conditional)
• Legacy ESLint/Prettier configs
• Obsolete build tool configurations

Success Criteria:

• Repository structure is clean and maintainable
• No accidental removal of required files
• Package publishing continues to work correctly

---

Phase 4: Compliance and Protection

Task 8: Develop Compliance Protection Strategy

Scope: Global monitoring system (covers all 30 repositories)

Objective: Establish monitoring and protection mechanisms to ensure all repository configurations and settings from Tasks 0-7 remain consistent and don't drift over time. Create safeguards to detect and prevent unauthorized changes to the standardized setup.

Technical Requirements:

• Create automated auditing system for repository configurations
• Implement monitoring for branch protection rules and workflow integrity
• Establish alerting mechanisms for configuration drift
• Develop restoration procedures for configuration compliance

Dependencies: All previous tasks (0-7) must be completed first

Deliverables:

• Configuration audit scripts created
• Automated monitoring system deployed
• Alert system for configuration drift configured
• Restoration procedures documented
• Compliance reporting dashboard established
• Change approval process documented

Files Created:

• Configuration audit scripts
• Monitoring service configuration
• Compliance reporting tools
• Restoration automation scripts

Success Criteria:

• All repository configurations remain consistent with established standards
• Configuration drift is detected within acceptable timeframes
• Unauthorized changes trigger immediate alerts
• Restoration procedures can quickly revert configurations to compliant state
• Compliance reports provide clear visibility into system health

Reference Implementation: Centralized compliance monitoring that validates all repositories maintain the exact configurations established in the upgrade process.

---

Risk Assessment and Mitigation

High-Risk Areas

1. Task Interdependencies: Tasks 4-7 must be completed together

   • Mitigation: Implement as atomic pull requests
   • Validation: Comprehensive testing after all tasks complete

2. Build System Migration: Potential breaking changes in test/build processes

   • Mitigation: Thorough testing in development environment first
   • Rollback Plan: Maintain backup branches before major changes

3. Import Path Changes: Risk of breaking external consumers

   • Mitigation: Maintain backward compatibility in package exports
   • Communication: Document any breaking changes clearly

Testing Strategy

1. Incremental Validation: Test each task completion before proceeding
2. Reference Implementation: Use successful repository as template
3. Automated Testing: Leverage existing test suites to validate functionality
4. Manual Verification: Confirm demo pages and documentation render correctly

Success Metrics

Quantitative Metrics

• 100% of repositories successfully upgraded
• Zero regression in existing functionality
• Build time performance maintained or improved
• Test suite execution time maintained or improved

Qualitative Metrics

• Improved developer experience with standardized tooling
• Reduced maintenance overhead with centralized workflows
• Enhanced code quality with modern linting tools
• Streamlined release process with automated configuration

Timeline and Resource Allocation

Phase 1 (Infrastructure): 1-2 days

• Task 0: Create auro-actions repository

Phase 2 (Configuration): 1 sprint

• Tasks 1-3: Repository setup and workflow migration

Phase 3 (Modernization): 1 sprint

• Tasks 4-7: Build system and package modernization

Phase 4 (Compliance Protection): 3-5 days

• Task 8: Develop compliance protection strategy and monitoring systems

Total Estimated Effort: ~140 hours across 2-3 sprints

Conclusion

This MVP Repository Upgrade Initiative represents a significant step toward modernizing our development infrastructure. By implementing standardized tooling, centralized workflows, and modern development practices, we will improve developer productivity, reduce maintenance overhead, and ensure consistency across all Auro repositories.

The structured approach with clear dependencies and comprehensive testing ensures a smooth transition while minimizing risk to existing functionality.