MokoConsulting/MokoCassiopeia
1
1
Fork 0
Code Issues 2 Pull Requests Actions Packages Releases 1 Activity

docs: update scripts README for current workflow

Browse Source 
Remove references to deleted build-release.sh and minify.js.
Document current CI-driven release process and remaining
download-google-fonts.sh script.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jonathan Miller
2026-04-07 18:51:44 -05:00
parent f5cca3487b
commit 20fbcabe87
1 changed files with 36 additions and 238 deletions
Download Patch File Download Diff File Expand all files Collapse all files

274
scripts/README.md
View File

@@ -1,271 +1,69 @@
<!-- Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
SPDX-License-Identifier: GPL-3.0-or-later
# FILE INFORMATION
DEFGROUP: Joomla.Template.Site
INGROUP: MokoCassiopeia.Documentation
REPO: https://github.com/mokoconsulting-tech/MokoCassiopeia
FILE: scripts/README.md
VERSION: 03.09.04
BRIEF: Documentation for utility scripts
-->
# Scripts — MokoCassiopeia # 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 ## 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**: **Usage**:
```bash ```bash
# Build with auto-detected version from templateDetails.xml ./scripts/download-google-fonts.sh
./scripts/build-release.sh
# Build with specific version
./scripts/build-release.sh 03.08.03
``` ```
**What it does**: Downloads font files and generates CSS `@font-face` declarations for local serving, avoiding external CDN dependencies.
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 ## 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 to `version/*` branches, manual dispatch.
**Triggers**:
- Push of version tag (e.g., `03.08.03`)
- Manual workflow dispatch with version input
**Process**: **Process**:
1. Checks out repository 1. Reads version from `templateDetails.xml`
2. Sets up PHP environment 2. Builds ZIP from `src/` contents
3. Installs dependencies (if composer.json exists) 3. Computes SHA-256 checksum
4. Updates version numbers in manifest files 4. Creates/updates GitHub Release with ZIP asset
5. Creates package structure 5. Updates `update.xml` with download URL and checksum
6. Builds ZIP package
7. Generates checksums
8. Creates GitHub Release with artifacts
**Usage**: ### update-server.yml
```bash
# Create and push a tag
git tag 03.08.04
git push origin 03.08.04
# Or use GitHub UI to run manually **Triggers**: Release published, manual dispatch.
```
---
### `.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**: **Process**:
1. Downloads the release package 1. Updates `updates.xml` with version, download URL, and SHA-256
2. Calculates SHA-256 hash 2. Commits changes to main
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 ## Release Process
### Manual Release (Local Build) All releases are automated via CI. To release:
1. **Update version numbers**: 1. Bump version in `src/templateDetails.xml`
```bash 2. Merge to main
# Update these files manually: 3. The workflow detects the version, builds the ZIP, and creates the release
# - src/templateDetails.xml
# - updates.xml
# - CHANGELOG.md
```
2. **Build package**: **Only create releases when `src/` has changes.** Non-src changes (docs, workflows, scripts) are cleanup and do not require a release.
```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/)
--- ---