Jonathan Miller
213 lines
13 KiB
Markdown
213 lines
13 KiB
Markdown
<!--
|
|
Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
|
|
|
|
SPDX-License-Identifier: GPL-3.0-or-later
|
|
|
|
# FILE INFORMATION
|
|
DEFGROUP: MokoStandards.Documentation
|
|
INGROUP: MokoStandards.Workflows
|
|
REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API
|
|
PATH: /docs/workflows/release-system.md
|
|
VERSION: 04.06.00
|
|
BRIEF: Documentation for the unified release system
|
|
-->
|
|
|
|
[](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards)
|
|
|
|
# Release System
|
|
|
|
## Overview
|
|
|
|
The MokoStandards release system uses a branch-based pipeline with platform-specific packaging. Releases flow through development, optional alpha/beta testing, release candidate, and production stages with automated GitHub Release creation, version archiving, and platform-aware asset publishing.
|
|
|
|
## Release Lifecycle
|
|
|
|
### Version Numbering
|
|
|
|
All version files use three-part format: `XX.YY.ZZ`
|
|
|
|
- **Patch 00** (`XX.YY.00`) = development only, no release created
|
|
- **Patch 01** (`XX.YY.01`) = first release for a minor version
|
|
- **Patch 02+** = subsequent releases (bug fixes, improvements)
|
|
|
|
### Branch Flow
|
|
|
|
```
|
|
dev → [alpha] → [beta] → rc → version/XX → main → dev
|
|
optional (integration) (production) (feedback)
|
|
```
|
|
|
|
1. **`dev/XX.YY`** or **`dev/feature-name`** — Active development. Patch is 00. No release.
|
|
2. **`alpha/XX.YY.ZZ`** — *(Optional)* Early internal testing. Can be skipped — dev can go straight to rc.
|
|
3. **`beta/XX.YY.ZZ`** — *(Optional)* Broader external testing. Can be skipped — dev can go straight to rc.
|
|
4. **`rc/XX.YY.ZZ`** — Release candidate. Three-part version required (patch >= 01). Auto-creates tracking issue + draft GitHub Release.
|
|
5. **`version/XX`** — Major version integration branch (major number only, e.g., `version/04`). All minors and patches flow into the same major branch.
|
|
6. **`main`** — Production. Push triggers `auto-release.yml` which publishes the GitHub Release, creates/updates the major tag, and auto-bumps patch.
|
|
7. **`main` merges back to `dev`** — Completes the cycle. Ensures dev has the latest production state.
|
|
|
|
### Release Tags
|
|
|
|
Each stability level has its own GitHub Release tag:
|
|
|
|
| Tag | Stability | Contents |
|
|
|-----|-----------|----------|
|
|
| `development` | Development | Dev ZIPs |
|
|
| `alpha` | Alpha | Alpha ZIPs |
|
|
| `beta` | Beta | Beta ZIPs |
|
|
| `release-candidate` | RC | RC ZIPs |
|
|
| `vXX` | Stable production | Stable ZIPs (major only, e.g., `v04`) |
|
|
|
|
- The `vXX` production tag is **major only** — one release per major version
|
|
## Workflow Location (v2)All workflows MUST be in `.gitea/workflows/` only. Gitea Actions does not run workflows from `.github/workflows/`. Having files in `.github/workflows/` creates ghost queued runs that block the runner.## Stream TagsReleases use stream-based git tags, NOT version numbers:- `stable` — production release- `release-candidate` — RC testing- `beta` — feature-complete stability testing- `alpha` — early testing- `development` — unstable dev buildsTo trigger a release, push the appropriate stream tag: `git tag -f stable && git push origin stable --force`## Cascade LogicEach stability level cascades to all lower levels in updates.xml:- **stable** → updates development, alpha, beta, rc, stable- **rc** → updates development, alpha, beta, rc- **beta** → updates development, alpha, beta- **alpha** → updates development, alpha- **development** → updates development only## SHA-256 Rules- Never leave `<sha256></sha256>` empty — Joomla fails checksum verification on empty tags- Omit the `<sha256>` tag entirely if no hash is available- Always set SHA when building a package## creationDateAlways update `<creationDate>` whenever version is bumped — in the manifest AND in updates.xml.## Auto-DetectionThe release workflow (`release.yml`) is fully generic:- `GITEA_REPO` derived from `github.event.repository.name`- `EXT_ELEMENT` auto-detected from the Joomla manifest `<element>` tag- Falls back to manifest filename, then repo name (lowercased)- No per-repo customization needed## Version History (Stable)Stable releases keep up to 5 previous versions in the Gitea release body.
|
|
- All minor+patch versions **append** release notes and ZIP assets to the same `vXX` release
|
|
- No minor or patch production tags are created
|
|
- Example: versions `04.01.01`, `04.02.00`, `04.03.05` all update the same `v04` release
|
|
- Pre-release tags (`development`, `alpha`, `beta`, `release-candidate`) are updated in-place
|
|
|
|
### Standard Release Process
|
|
|
|
1. **Start development**: Create `dev/XX.YY` branch from main
|
|
2. **Develop**: Work on the dev branch with version set to `XX.YY.00`
|
|
3. **Alpha testing** *(optional)*: Create `alpha/XX.YY.ZZ` branch from dev for early internal testing. Can be skipped.
|
|
4. **Beta testing** *(optional)*: Create `beta/XX.YY.ZZ` branch from alpha (or dev) for broader external testing. Can be skipped.
|
|
5. **Create RC**: Create `rc/XX.YY.01` branch from beta, alpha, or dev. This auto-creates a tracking issue with 5 sub-issues and a draft GitHub Release
|
|
6. **Test RC**: Fix bugs on the RC branch. Deploy to dev server for final testing
|
|
7. **Merge to version/XX**: Merge RC to the `version/XX` major integration branch
|
|
8. **Merge to main**: Merge `version/XX` to main via PR. `auto-release.yml` fires:
|
|
- Publishes the draft release (or creates new one)
|
|
- Uploads platform-specific assets (ZIP for Joomla, etc.)
|
|
- Creates/updates the `vXX` tag
|
|
- Auto-bumps patch version with `[skip ci]` commit
|
|
9. **Feedback loop**: Main merges back to dev to start the next cycle
|
|
|
|
## Platform-Specific Pipelines
|
|
|
|
### Generic Repos
|
|
|
|
- `auto-release.yml`: Creates GitHub Release with changelog notes, `vXX` tag
|
|
- `deploy-dev.yml`: FTP deploy on push to `dev/**`, `alpha/**`, `beta/**`, or `rc/**`
|
|
- `deploy-demo.yml`: FTP deploy on push to `main`
|
|
- `changelog-validation.yml`: Validates CHANGELOG.md format on PRs
|
|
|
|
### Joomla Repos (waas-component)
|
|
|
|
Joomla repos do **not** use automatic FTP deploy workflows. Distribution is via `updates.xml` + GitHub Release ZIPs + manual dev deploy.
|
|
|
|
- `auto-release.yml`: Builds ZIP from `src/`, uploads to major release, writes SHA-256 in `updates.xml`
|
|
- `update-server.yml`: Writes dev/alpha/beta/rc entries to `updates.xml` on branch push
|
|
- `deploy-manual.yml`: Manual workflow_dispatch FTP deploy for dev testing (no automatic deploy)
|
|
- `ci-joomla.yml`: Manifest validation, language file checks, XML lint
|
|
- `repo_health.yml`: Platform-aware health checks
|
|
- `changelog-validation.yml`: Validates CHANGELOG.md format on PRs
|
|
|
|
### Dolibarr Repos (crm-module, crm-platform)
|
|
|
|
- `auto-release.yml`: Creates GitHub Release, updates `update.txt` and module descriptor version
|
|
- `deploy-dev.yml` / `deploy-demo.yml`: FTP deploy
|
|
- `publish-to-mokodolimods.yml`: Publishes to MokoDolimods marketplace (crm-module only)
|
|
- `ci-dolibarr.yml`: Module descriptor validation, PHP lint
|
|
- `repo_health.yml`: Platform-aware health checks
|
|
- `changelog-validation.yml`: Validates CHANGELOG.md format on PRs
|
|
|
|
## Version Format Summary
|
|
|
|
| Context | Format | Example |
|
|
|---------|--------|---------|
|
|
| Version files | `XX.YY.ZZ` (three-part always) | `04.06.00` |
|
|
| Dev branches | `XX.YY` or `XX.YY.ZZ` or `feature-name` | `dev/04.06`, `dev/sidebar-fix` |
|
|
| Alpha branches | `XX.YY.ZZ` (three-part, optional stage) | `alpha/04.06.01` |
|
|
| Beta branches | `XX.YY.ZZ` (three-part, optional stage) | `beta/04.06.01` |
|
|
| RC branches | `XX.YY.ZZ` (three-part required) | `rc/04.06.01` |
|
|
| Version branches | `XX` (major only) | `version/04` |
|
|
| Release tags (stable) | `vXX` (major only) | `v04` |
|
|
| Release tags (pre) | Named per stability level | `development`, `alpha`, `beta`, `release-candidate` |
|
|
|
|
## Version Detection
|
|
|
|
The `auto-release.yml` workflow reads the version from the `VERSION:` field in the README.md FILE INFORMATION block. This is the single source of truth for the release version.
|
|
|
|
## Skipping Releases
|
|
|
|
To prevent automatic release creation, include `[skip ci]` in your commit message:
|
|
|
|
```bash
|
|
git commit -m "docs: update README [skip ci]"
|
|
```
|
|
|
|
Commits by `gitea-actions[bot]` are also skipped automatically (e.g., auto-bump commits).
|
|
|
|
## Architecture
|
|
|
|
### Full Release Cycle
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ dev → [alpha] → [beta] → rc → version/XX → main │
|
|
│ optional optional │ │
|
|
│ └──→ dev│
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Auto-Release Pipeline (on push to main)
|
|
|
|
```
|
|
┌──────────────────────────────────────────────────────────┐
|
|
│ Push to main branch │
|
|
│ (version in README.md FILE INFORMATION) │
|
|
└────────────────────┬─────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌──────────────────────────────────────────────────────────┐
|
|
│ auto-release.yml (Detect + Route) │
|
|
│ • Read VERSION from README.md │
|
|
│ • Check if vXX tag exists (major-only) │
|
|
│ • Detect platform (.mokostandards → platform field) │
|
|
└────────────────────┬─────────────────────────────────────┘
|
|
│
|
|
┌──────────┼──────────┐
|
|
▼ ▼ ▼
|
|
┌──────────┐ ┌──────────┐ ┌──────────────┐
|
|
│ Generic │ │ Joomla │ │ Dolibarr │
|
|
│ │ │ │ │ │
|
|
│ Tag vXX │ │ Build ZIP│ │ Update │
|
|
│ Release │ │ SHA-256 │ │ update.txt │
|
|
│ notes │ │ update │ │ mod*.class │
|
|
│ │ │ .xml │ │ Tag + release│
|
|
└──────────┘ └──────────┘ └──────────────┘
|
|
│
|
|
▼
|
|
┌──────────────────────────────────────────────────────────┐
|
|
│ GitHub Release (one per major) │
|
|
│ • Create or update vXX release │
|
|
│ • Append release notes for this minor.patch │
|
|
│ • Upload ZIP assets (Joomla) │
|
|
│ • Auto-bump patch version ([skip ci]) │
|
|
│ • Main merges back to dev (feedback loop) │
|
|
└──────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Configuration Files
|
|
|
|
- `.gitea/workflows/auto-release.yml` - Main release workflow (platform-aware)
|
|
- `.gitea/workflows/update-server.yml` - Joomla updates.xml generation for dev/alpha/beta/rc
|
|
- `.gitea/workflows/changelog-validation.yml` - CHANGELOG.md format validation
|
|
- `.mokostandards` - Platform configuration (`platform: joomla|dolibarr|generic`)
|
|
- `README.md` - VERSION field (single source of truth)
|
|
- `CHANGELOG.md` - Release notes source
|
|
|
|
## Best Practices
|
|
|
|
1. **Patch 00 is always dev** — never release from patch 00
|
|
2. **RC before release** — always go through `rc/` before merging to main (alpha/beta are optional)
|
|
3. **Alpha and beta are optional** — dev can go straight to rc when internal/external testing stages are not needed
|
|
4. **One major release object** — all minor+patch append to the same `vXX` GitHub Release
|
|
5. **Let auto-bump handle patch** — don't manually bump patch on main
|
|
6. **Write clear changelog entries** before creating RC
|
|
7. **Test RC on dev server** — RC branches deploy to dev FTP (Dolibarr/Generic) or generate dev updates.xml entries (Joomla)
|
|
8. **Main feeds back to dev** — always merge main back to dev after a release to start the next cycle
|
|
|
|
---
|
|
|
|
**Last Updated**: 2026-04-07
|
|
**Maintained by**: Moko Consulting Infrastructure Team
|