MokoCassiopeia/scripts/README.md

Scripts — MokoCassiopeia

This directory contains utility scripts for building, releasing, and managing the MokoCassiopeia Joomla template.

Available Scripts

build-release.sh

Purpose: Build a release package for MokoCassiopeia template.

Usage:

# Build with auto-detected version from templateDetails.xml
./scripts/build-release.sh

# Build with specific version
./scripts/build-release.sh 03.08.03

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

---

Automated Workflows

The repository includes GitHub Actions workflows that automate the build and release process:

.github/workflows/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

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

Usage:

# Create and push a tag
git tag 03.08.04
git push origin 03.08.04

# 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

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

---

Release Process

Manual Release (Local Build)

1. Update version numbers:

   # Update these files manually:
   # - src/templateDetails.xml
   # - updates.xml
   # - CHANGELOG.md
   

2. Build package:

   ./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:

   # 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:

   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

# 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

# Ubuntu/Debian
sudo apt-get install rsync

# macOS
brew install rsync

Problem: zip: command not found

# 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
• Email: hello@mokoconsulting.tech
• Documentation: docs/

---

License

All scripts are licensed under GPL-3.0-or-later.

Copyright (C) 2026 Moko Consulting