docs: update scripts README for current workflow
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:
@@ -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
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user