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

Add comprehensive release process documentation

Browse Source 
Co-authored-by: jmiller-moko <230051081+jmiller-moko@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
2026-02-27 04:32:47 +00:00
parent 63a7b9dbb4
commit caee98f7c3
2 changed files with 645 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/README.md
View File

@@ -45,9 +45,15 @@ This directory contains comprehensive documentation for the MokoCassiopeia Jooml
* **[Workflow Guide](WORKFLOW_GUIDE.md)** - Complete workflow reference
* Git branching strategy
* Development workflow
* Release process
* Pull request guidelines
* **[Release Process](RELEASE_PROCESS.md)** ⭐ - Complete release documentation
* Automated release workflow with GitHub Actions
* Manual release procedures
* Update server configuration
* Testing and rollback procedures
* Build scripts and tools
* **[Joomla Development Guide](JOOMLA_DEVELOPMENT.md)** - Joomla-specific development
* Testing with Codeception
* PHP quality checks (PHPStan, PHPCS)

638
docs/RELEASE_PROCESS.md Normal file
View File

@@ -0,0 +1,638 @@
<!--
Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
This file is part of a Moko Consulting project.
SPDX-License-Identifier: GPL-3.0-or-later
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.
# FILE INFORMATION
DEFGROUP: Joomla.Template.Site
INGROUP: MokoCassiopeia.Documentation
REPO: https://github.com/mokoconsulting-tech/MokoCassiopeia
FILE: docs/RELEASE_PROCESS.md
VERSION: 01.00.00
BRIEF: Complete release process documentation for MokoCassiopeia
PATH: /docs/RELEASE_PROCESS.md
-->
# Release Process — MokoCassiopeia
This document describes the complete release process for MokoCassiopeia Joomla template, including automated workflows and manual procedures.
## Table of Contents
1. [Overview](#overview)
2. [Release Types](#release-types)
3. [Automated Release Process](#automated-release-process)
4. [Manual Release Process](#manual-release-process)
5. [Update Server Configuration](#update-server-configuration)
6. [Testing Releases](#testing-releases)
7. [Rollback Procedures](#rollback-procedures)
8. [Troubleshooting](#troubleshooting)
---
## Overview
MokoCassiopeia uses an automated release system powered by GitHub Actions. The system:
- **Builds** installation packages automatically
- **Generates** checksums for security verification
- **Creates** GitHub Releases with downloadable artifacts
- **Updates** the Joomla update server (`updates.xml`) automatically
- **Validates** package integrity with SHA-256 hashes
### Key Components
1. **Release Workflow** (`.github/workflows/release.yml`): Builds and publishes releases
2. **Auto-Update SHA** (`.github/workflows/auto-update-sha.yml`): Updates `updates.xml` after release
3. **Build Script** (`scripts/build-release.sh`): Local development builds
4. **Update Server** (`updates.xml`): Joomla update server manifest
---
## Release Types
### Patch Release (Third Digit)
**Format**: `XX.XX.XX` → `XX.XX.XX+1` (e.g., `03.08.03` → `03.08.04`)
**When to use**:
- Bug fixes
- Security patches
- Documentation updates
- Minor CSS/styling tweaks
- No breaking changes
**Example**: `03.08.03` → `03.08.04`
### Minor Release (Second Digit)
**Format**: `XX.XX.00` → `XX.XX+1.00` (e.g., `03.08.03` → `03.09.00`)
**When to use**:
- New features
- New module/component overrides
- Significant styling changes
- Backward-compatible changes
**Example**: `03.08.03` → `03.09.00`
### Major Release (First Digit)
**Format**: `XX.00.00` → `XX+1.00.00` (e.g., `03.08.03` → `04.00.00`)
**When to use**:
- Breaking changes
- Major architecture changes
- Joomla version upgrades
- Complete redesigns
**Example**: `03.08.03` → `04.00.00`
---
## Automated Release Process
**Recommended for most releases**
### Prerequisites
- [ ] All changes merged to `main` branch
- [ ] Tests passing
- [ ] Documentation updated
- [ ] CHANGELOG.md updated
- [ ] Local testing completed
### Step 1: Prepare Release Branch
```bash
# Create release branch
git checkout main
git pull
git checkout -b release/03.08.04
# Update version in templateDetails.xml
# Edit: src/templates/templateDetails.xml
# Change: <version>03.08.03</version>
# To: <version>03.08.04</version>
# Update CHANGELOG.md
# Add new section:
## [03.08.04] - 2026-02-27
### Added
- Feature descriptions
### Fixed
- Bug fix descriptions
### Changed
- Change descriptions
# Commit changes
git add src/templates/templateDetails.xml CHANGELOG.md
git commit -m "chore: Prepare release 03.08.04"
git push origin release/03.08.04
```
### Step 2: Create Pull Request
1. Go to GitHub repository
2. Click "Pull requests" → "New pull request"
3. Base: `main`, Compare: `release/03.08.04`
4. Title: `Release 03.08.04`
5. Description: Copy relevant CHANGELOG entries
6. Create pull request
7. Review and merge
### Step 3: Create and Push Tag
```bash
# Switch to main and pull changes
git checkout main
git pull
# Create tag
git tag 03.08.04
# Push tag (triggers release workflow)
git push origin 03.08.04
```
### Step 4: Monitor Automated Process
1. **Go to GitHub Actions tab**
2. **Watch "Create Release" workflow**:
- Builds package
- Generates checksums
- Creates GitHub Release
- Uploads artifacts
3. **Watch "Auto-Update SHA Hash" workflow**:
- Downloads release package
- Calculates SHA-256 hash
- Updates `updates.xml`
- Commits to main branch
### Step 5: Verify Release
1. **Check GitHub Release**:
- Go to Releases tab
- Verify release `03.08.04` exists
- Download ZIP package
- Verify checksums match
2. **Check updates.xml**:
```bash
git pull
cat updates.xml
```
- Verify version is `03.08.04`
- Verify download URL is correct
- Verify SHA-256 hash is present
3. **Test Joomla Update**:
- Install previous version in Joomla
- Go to Extensions → Update
- Verify update is detected
- Perform update
- Verify template works correctly
---
## Manual Release Process
**Use when automation fails or for local testing**
### Step 1: Prepare Repository
```bash
# Update version numbers
# Edit: src/templates/templateDetails.xml
# Edit: CHANGELOG.md
# Commit changes
git add src/templates/templateDetails.xml CHANGELOG.md
git commit -m "chore: Prepare release 03.08.04"
git push
```
### Step 2: Build Package Locally
```bash
# Run build script
./scripts/build-release.sh 03.08.04
# Output will be in build/ directory:
# - mokocassiopeia-src-03.08.04.zip
# - mokocassiopeia-src-03.08.04.zip.sha256
# - mokocassiopeia-src-03.08.04.zip.md5
```
### Step 3: Test Package
```bash
# Install in Joomla test environment
# Extensions → Manage → Install → Upload Package File
# Select: build/mokocassiopeia-src-03.08.04.zip
# Test all features:
# - Template displays correctly
# - Module overrides work
# - Alternative layouts selectable
# - Dark mode works
# - No JavaScript errors
```
### Step 4: Create GitHub Release
1. **Go to GitHub Releases**
2. **Click "Create a new release"**
3. **Tag**: `03.08.04` (create new tag)
4. **Release title**: `Release 03.08.04`
5. **Description**: Copy from CHANGELOG.md
6. **Upload files**:
- `mokocassiopeia-src-03.08.04.zip`
- `mokocassiopeia-src-03.08.04.zip.sha256`
- `mokocassiopeia-src-03.08.04.zip.md5`
7. **Publish release**
### Step 5: Update updates.xml Manually
```bash
# Extract SHA-256 hash
cat build/mokocassiopeia-src-03.08.04.zip.sha256
# Example output: a1b2c3d4e5f6...
# Edit updates.xml
# Update <version>03.08.04</version>
# Update <creationDate>2026-02-27</creationDate>
# Update <downloadurl>https://github.com/mokoconsulting-tech/MokoCassiopeia/releases/download/03.08.04/mokocassiopeia-src-03.08.04.zip</downloadurl>
# Update <sha256>sha256:a1b2c3d4e5f6...</sha256>
# Commit and push
git add updates.xml
git commit -m "chore: Update updates.xml for release 03.08.04"
git push
```
---
## Update Server Configuration
### updates.xml Structure
```xml
<updates>
<update>
<name>MokoCassiopeia</name>
<description>Moko Consulting's site template based on Cassiopeia.</description>
<element>mokocassiopeia</element>
<type>template</type>
<client>site</client>
<version>03.08.04</version>
<creationDate>2026-02-27</creationDate>
<author>Jonathan Miller || Moko Consulting</author>
<authorEmail>hello@mokoconsulting.tech</authorEmail>
<copyright>(C)GNU General Public License Version 3 - 2026 Moko Consulting</copyright>
<infourl title='MokoCassiopeia'>https://github.com/mokoconsulting-tech/MokoCassiopeia</infourl>
<downloads>
<downloadurl type='full' format='zip'>https://github.com/mokoconsulting-tech/MokoCassiopeia/releases/download/03.08.04/mokocassiopeia-src-03.08.04.zip</downloadurl>
<sha256>sha256:a1b2c3d4e5f6...</sha256>
</downloads>
<tags>
<tag>stable</tag>
</tags>
<maintainer>Moko Consulting</maintainer>
<maintainerurl>https://www.mokoconsulting.tech</maintainerurl>
<targetplatform name='joomla' version='5.*'/>
</update>
</updates>
```
### Hosting Update Server
The `updates.xml` file is hosted directly on GitHub:
**URL**: `https://raw.githubusercontent.com/mokoconsulting-tech/MokoCassiopeia/main/updates.xml`
This URL is configured in `src/templates/templateDetails.xml`:
```xml
<updateservers>
<server type="extension" name="MokoCassiopeia Updates" priority="1">
https://raw.githubusercontent.com/mokoconsulting-tech/MokoCassiopeia/main/updates.xml
</server>
</updateservers>
```
---
## Testing Releases
### Pre-Release Testing
```bash
# 1. Build package locally
./scripts/build-release.sh
# 2. Set up Joomla test environment
# - Clean Joomla 5.x installation
# - Previous MokoCassiopeia version installed
# 3. Test current version features
# - All module overrides
# - Alternative layouts
# - Dark mode toggle
# - Responsive behavior
# 4. Install new package
# Extensions → Manage → Install → Upload Package
# 5. Verify upgrade process
# - No errors during installation
# - Settings preserved
# - Custom modifications retained
# 6. Test new features
# - New functionality works
# - Bug fixes applied
# - No regressions
```
### Update Server Testing
```bash
# 1. Install previous version in Joomla
# 2. Go to: Extensions → Update
# 3. Click "Find Updates"
# 4. Verify update shows: "MokoCassiopeia 03.08.04"
# 5. Click "Update"
# 6. Verify successful update
# 7. Test template functionality
```
### Checklist
- [ ] Package installs without errors
- [ ] Template activates correctly
- [ ] All module overrides work
- [ ] Alternative layouts selectable
- [ ] Dark mode functions
- [ ] Responsive on mobile/tablet/desktop
- [ ] No JavaScript console errors
- [ ] No PHP errors in Joomla logs
- [ ] Update server detects new version
- [ ] Update process completes successfully
---
## Rollback Procedures
### Rollback Release
If a release has critical issues:
1. **Delete GitHub Release**:
- Go to Releases
- Click release to delete
- Click "Delete"
- Confirm deletion
2. **Delete Git Tag**:
```bash
# Delete local tag
git tag -d 03.08.04
# Delete remote tag
git push --delete origin 03.08.04
```
3. **Revert updates.xml**:
```bash
# Revert to previous version
git revert <commit-hash-of-auto-update>
git push
```
4. **Notify Users**:
- Create GitHub issue explaining the problem
- Pin the issue
- Provide rollback instructions for users
### User Rollback Instructions
For users who installed the problematic version:
1. **Download previous version** from GitHub Releases
2. **Uninstall current version**:
- Extensions → Manage → Manage
- Find MokoCassiopeia
- Click "Uninstall"
3. **Install previous version**:
- Extensions → Manage → Install
- Upload previous version ZIP
4. **Verify functionality**
---
## Troubleshooting
### Release Workflow Fails
**Problem**: Build fails with "rsync: command not found"
**Solution**: The GitHub Actions runner always has rsync installed. If this occurs, check the workflow file syntax.
**Problem**: ZIP creation fails
**Solution**: Check that `src/templates/` and `src/media/` directories exist and contain files.
**Problem**: Version update fails
**Solution**: Verify `sed` commands in workflow match actual XML structure.
### Auto-Update SHA Fails
**Problem**: Cannot download release package
**Solution**:
- Verify release was published (not draft)
- Check package naming: `mokocassiopeia-src-{version}.zip`
- Verify release tag format
**Problem**: SHA-256 hash mismatch
**Solution**:
- Package may have been modified after calculation
- Re-run the workflow manually
- Verify package integrity
**Problem**: Commit fails
**Solution**:
- Check workflow has write permissions
- Verify no branch protection rules blocking bot commits
### Manual Build Issues
**Problem**: `./scripts/build-release.sh: Permission denied`
**Solution**:
```bash
chmod +x scripts/build-release.sh
./scripts/build-release.sh
```
**Problem**: Build directory exists
**Solution**:
```bash
rm -rf build/
./scripts/build-release.sh
```
### Update Server Issues
**Problem**: Joomla doesn't detect update
**Solution**:
1. Check `updates.xml` is accessible:
```bash
curl https://raw.githubusercontent.com/mokoconsulting-tech/MokoCassiopeia/main/updates.xml
```
2. Verify version number is higher than installed version
3. Clear Joomla cache: System → Clear Cache
4. Check update URL in templateDetails.xml
**Problem**: Update fails with "Invalid package"
**Solution**:
- Verify SHA-256 hash matches
- Re-download package and check integrity
- Verify package structure is correct
---
## Best Practices
### Version Numbering
- **Always increment** version numbers sequentially
- **Never reuse** version numbers
- **Use consistent** format: `XX.XX.XX`
### Changelog
- **Update before** release
- **Include all changes** since last version
- **Categorize** changes: Added, Changed, Fixed, Removed
- **Write clear descriptions** for users
### Testing
- **Test locally** before pushing tag
- **Test update process** from previous version
- **Test on clean** Joomla installation
- **Test different** configurations
### Communication
- **Announce releases** on GitHub Discussions
- **Document breaking changes** clearly
- **Provide migration guides** for major changes
- **Respond promptly** to issue reports
---
## Quick Reference
### Automated Release Commands
```bash
# 1. Create release branch
git checkout -b release/03.08.04
# 2. Update version and CHANGELOG
# (edit files)
# 3. Commit and push
git add .
git commit -m "chore: Prepare release 03.08.04"
git push origin release/03.08.04
# 4. Create and merge PR (via GitHub UI)
# 5. Create and push tag
git checkout main
git pull
git tag 03.08.04
git push origin 03.08.04
# 6. Wait for automation to complete
```
### Manual Release Commands
```bash
# Build locally
./scripts/build-release.sh 03.08.04
# Test installation
# (manual Joomla testing)
# Create release on GitHub
# (via GitHub UI)
# Update updates.xml
# (edit file with SHA-256)
git add updates.xml
git commit -m "chore: Update updates.xml for 03.08.04"
git push
```
---
## Related Documentation
- **Build Scripts**: [scripts/README.md](../scripts/README.md)
- **Workflow Guide**: [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md)
- **Contributing**: [CONTRIBUTING.md](../CONTRIBUTING.md)
- **Changelog**: [CHANGELOG.md](../CHANGELOG.md)
---
## Support
- **Issues**: [GitHub Issues](https://github.com/mokoconsulting-tech/MokoCassiopeia/issues)
- **Discussions**: [GitHub Discussions](https://github.com/mokoconsulting-tech/MokoCassiopeia/discussions)
- **Email**: hello@mokoconsulting.tech
---
## License
Copyright (C) 2026 Moko Consulting
This documentation is licensed under GPL-3.0-or-later.