diff --git a/scripts/README.md b/scripts/README.md index 0c3f452..995b9dd 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -1,271 +1,69 @@ + + # Scripts — MokoCassiopeia -This directory contains utility scripts for building, releasing, and managing the MokoCassiopeia Joomla template. +Utility scripts for managing the MokoCassiopeia Joomla template. ## Available Scripts -### build-release.sh +### download-google-fonts.sh -**Purpose**: Build a release package for MokoCassiopeia template. +**Purpose**: Download Google Fonts for local hosting. **Usage**: ```bash -# Build with auto-detected version from templateDetails.xml -./scripts/build-release.sh - -# Build with specific version -./scripts/build-release.sh 03.08.03 +./scripts/download-google-fonts.sh ``` -**What it does**: -1. Creates a `build/` directory -2. Copies template files from `src/` -3. Copies media files from `src/media/` to `media/` -4. Creates a ZIP package: `mokocassiopeia-src-{version}.zip` -5. Generates SHA-256 and MD5 checksums -6. Outputs package location and checksums - -**Output**: -- `build/mokocassiopeia-src-{version}.zip` - Installation package -- `build/mokocassiopeia-src-{version}.zip.sha256` - SHA-256 checksum -- `build/mokocassiopeia-src-{version}.zip.md5` - MD5 checksum - -**Requirements**: -- `rsync` for file copying -- `zip` for package creation -- `sha256sum` and `md5sum` for checksums +Downloads font files and generates CSS `@font-face` declarations for local serving, avoiding external CDN dependencies. --- -## Automated Workflows +## Build & Release -The repository includes GitHub Actions workflows that automate the build and release process: +Builds and releases are handled entirely by GitHub Actions workflows. There are no local build scripts. -### `.github/workflows/release.yml` +### auto-release.yml -**Purpose**: Automated release creation when tags are pushed. - -**Triggers**: -- Push of version tag (e.g., `03.08.03`) -- Manual workflow dispatch with version input +**Triggers**: Push to `version/*` branches, manual dispatch. **Process**: -1. Checks out repository -2. Sets up PHP environment -3. Installs dependencies (if composer.json exists) -4. Updates version numbers in manifest files -5. Creates package structure -6. Builds ZIP package -7. Generates checksums -8. Creates GitHub Release with artifacts +1. Reads version from `templateDetails.xml` +2. Builds ZIP from `src/` contents +3. Computes SHA-256 checksum +4. Creates/updates GitHub Release with ZIP asset +5. Updates `update.xml` with download URL and checksum -**Usage**: -```bash -# Create and push a tag -git tag 03.08.04 -git push origin 03.08.04 +### update-server.yml -# Or use GitHub UI to run manually -``` - ---- - -### `.github/workflows/auto-update-sha.yml` - -**Purpose**: Automatically update SHA-256 hash in `updates.xml` after a release is published. - -**Triggers**: -- GitHub Release published -- Manual workflow dispatch with tag input +**Triggers**: Release published, manual dispatch. **Process**: -1. Downloads the release package -2. Calculates SHA-256 hash -3. Updates `updates.xml` with: - - New version number - - Current date - - Download URL - - SHA-256 hash -4. Commits and pushes changes to main branch - -**Benefits**: -- Ensures `updates.xml` always has correct SHA-256 hash -- Enables Joomla update server functionality -- Reduces manual update errors -- Automates security verification +1. Updates `updates.xml` with version, download URL, and SHA-256 +2. Commits changes to main --- ## Release Process -### Manual Release (Local Build) +All releases are automated via CI. To release: -1. **Update version numbers**: - ```bash - # Update these files manually: - # - src/templateDetails.xml - # - updates.xml - # - CHANGELOG.md - ``` +1. Bump version in `src/templateDetails.xml` +2. Merge to main +3. The workflow detects the version, builds the ZIP, and creates the release -2. **Build package**: - ```bash - ./scripts/build-release.sh 03.08.04 - ``` - -3. **Test package**: - - Install ZIP in Joomla test environment - - Verify all features work correctly - -4. **Create GitHub Release**: - - Go to GitHub Releases - - Click "Create a new release" - - Upload the ZIP, SHA256, and MD5 files - - Add release notes from CHANGELOG.md - -5. **Update updates.xml**: - - Copy SHA-256 hash from `.sha256` file - - Update `updates.xml` with new hash - - Commit and push changes - ---- - -### Automated Release (GitHub Actions) - -1. **Update version numbers**: - ```bash - # Update these files in a branch: - # - src/templateDetails.xml - # - CHANGELOG.md - - git checkout -b release/03.08.04 - # Make changes - git commit -m "chore: Prepare release 03.08.04" - git push origin release/03.08.04 - ``` - -2. **Create and merge PR**: - - Create PR from release branch - - Review changes - - Merge to main - -3. **Create and push tag**: - ```bash - git checkout main - git pull - git tag 03.08.04 - git push origin 03.08.04 - ``` - -4. **Automated process**: - - GitHub Actions builds package automatically - - Creates GitHub Release with artifacts - - `auto-update-sha` workflow updates `updates.xml` - -5. **Verify**: - - Check GitHub Release is created - - Verify `updates.xml` has correct SHA-256 - - Test Joomla update server - ---- - -## Development Workflow - -### Testing Local Builds - -```bash -# Build current version -./scripts/build-release.sh - -# Install in Joomla -# Navigate to Extensions > Manage > Install > Upload Package File -# Select: build/mokocassiopeia-src-{version}.zip -``` - -### Pre-Release Checklist - -- [ ] All code changes merged to main -- [ ] Version numbers updated: - - [ ] `src/templateDetails.xml` - - [ ] `CHANGELOG.md` -- [ ] CHANGELOG.md updated with release notes -- [ ] Tests passing -- [ ] Documentation updated -- [ ] Local build tested in Joomla - ---- - -## Troubleshooting - -### Build Fails - -**Problem**: `rsync: command not found` -```bash -# Ubuntu/Debian -sudo apt-get install rsync - -# macOS -brew install rsync -``` - -**Problem**: `zip: command not found` -```bash -# Ubuntu/Debian -sudo apt-get install zip - -# macOS (usually pre-installed) -brew install zip -``` - -### GitHub Actions Fails - -**Problem**: Release workflow fails on tag push - -Check: -1. Tag format matches pattern: `[0-9][0-9].[0-9][0-9].[0-9][0-9]` -2. Repository has write permissions for GITHUB_TOKEN -3. `src/` and `src/media/` directories exist - -**Problem**: auto-update-sha fails - -Check: -1. Release package was published successfully -2. Workflow has write permissions -3. Package naming matches expected format - ---- - -## File Structure - -``` -scripts/ -├── README.md # This file -└── build-release.sh # Local build script - -.github/workflows/ -├── release.yml # Automated release workflow -└── auto-update-sha.yml # SHA hash update workflow -``` - ---- - -## Contributing - -When adding new scripts: - -1. Add GPL-3.0-or-later license header -2. Include FILE INFORMATION block -3. Add usage documentation in this README -4. Make scripts executable: `chmod +x scripts/your-script.sh` -5. Test thoroughly before committing - ---- - -## Support - -- **Issues**: [GitHub Issues](https://github.com/mokoconsulting-tech/MokoCassiopeia/issues) -- **Email**: hello@mokoconsulting.tech -- **Documentation**: [docs/](../docs/) +**Only create releases when `src/` has changes.** Non-src changes (docs, workflows, scripts) are cleanup and do not require a release. ---