2

automation-branch-version-automation.-

Jonathan Miller edited this page 2026-05-11 21:56:18 +00:00

Table of Contents

• Branch and Version Automation - Comprehensive Guide
• Overview
• Quick Links
• Required Scripts (9 Total)
• Version Automation
• Semantic Version Bump Rules
• Quick Start
• Enterprise Features
• CLI Reference
• Branch Management
• Automated Branch Cleanup
• Release Version Management
• Release Automation
• Unified Release
• Release Types
• Platform Detection
• Extension Packaging
• Terraform Distribution
• Deployment
• Configuration Files
• Troubleshooting
• Version Not Found
• Permission Denied
• Failed Mid-Operation
• Debug Mode
• Integration Patterns
• Gitea Actions
• Pre-commit Hook
• Best Practices
• Version Management
• Branch Management
• Release Automation
• Reference
• Related Documentation
• External Resources
• Support
• Document Version: 1.0.0 Next Review: 2026-03-10 Maintainer: moko-platform Team

← Home

⚠️ DEPRECATED DOCUMENTATION
Status: REMOVED — This Python-based automation system has been replaced by PHP scripts. See api/automation/.
Last Updated: 2026-02-10
Current Status: moko-platform uses PHP-based automation (see Automation Scripts)

Branch and Version Automation - Comprehensive Guide

Document Version: 1.0.0
Last Updated: 2026-02-10
Status: Production Ready
Audience: Developers, DevOps Engineers, Repository Maintainers

Overview

This guide provides comprehensive documentation for the branch and version automation systems deployed across all moko-platform organization repositories via Terraform.

Quick Links

• Version Automation
• Branch Management
• Release Automation
• Terraform Distribution
• Troubleshooting

Required Scripts (9 Total)

All organization repositories automatically receive these scripts:

Script	Category	Purpose	Auto-Sync
version_bump_detector.py	Core Library	Semantic version detection	✅
detect_version_bump.py	Automation	Version bump CLI	✅
common.py	Core Library	Shared utilities	⚠️
clean_old_branches.py	Maintenance	Branch cleanup	✅
release_version.py	Maintenance	Release management	✅
unified_release.py	Release	Release orchestration	✅
detect_platform.py	Release	Platform detection	✅
package_extension.py	Release	Extension packaging	✅
test_version_bump_detector.py	Testing	Unit tests	✅

Version Automation

Semantic Version Bump Rules

Breaking change         → MAJOR (X.y.z)
New feature             → MINOR (x.Y.z)
Bug fix                 → PATCH (x.y.Z)
Documentation update    → PATCH (x.y.Z)
Performance improvement → PATCH (x.y.Z)
Code refactoring        → PATCH (x.y.Z)
Dependency update       → PATCH (x.y.Z)
Security fix            → PATCH (x.y.Z)

Quick Start

Detect version bump:

./api/automation/detect_version_bump.py --file pr_template.md

Apply version bump:

./api/automation/detect_version_bump.py \
  --text "New feature" \
  --apply \
  --stats

Enterprise Features

• ✅ Audit Logging: Complete operation trail in JSON format
• ✅ Backup/Rollback: Automatic backup before modifications
• ✅ SHA-256 Integrity: File integrity validation
• ✅ Performance Metrics: Detailed statistics
• ✅ Dry-Run Mode: Preview changes safely

Audit Log Location: logs/automation/version_bump_*.json

CLI Reference

./api/automation/detect_version_bump.py [OPTIONS]

Input Sources:
  --file FILE              Read from file
  --stdin                  Read from stdin
  --text TEXT              Analyze text
  --checkboxes TEXT        Analyze checkboxes

Actions:
  --apply                  Apply version bump
  --dry-run                Preview only

Options:
  --bump-type {major,minor,patch}  Override detection
  --backup / --no-backup           Toggle backup
  --audit-log / --no-audit-log     Toggle logging
  --verbose, -v                    Verbose output
  --json                           JSON output
  --stats                          Performance stats

Branch Management

Automated Branch Cleanup

List old branches:

./api/maintenance/clean_old_branches.py --days 90 --list

Delete with dry-run:

./api/maintenance/clean_old_branches.py --days 90 --delete --dry-run

Actually delete:

./api/maintenance/clean_old_branches.py --days 90 --delete --yes

Protected Branches (never deleted):

• main, master, dev, staging, production

Release Version Management

Create release:

./api/maintenance/release_version.py --version 1.3.0 --yes

Update CHANGELOG only:

./api/maintenance/release_version.py --version 1.3.0 --changelog-only

What it does:

1. Moves UNRELEASED to versioned section
2. Updates VERSION in headers
3. Creates git tags (optional)
4. Triggers GitHub releases (optional)

Release Automation

Unified Release

Create stable release:

./scripts/release/unified_release.py --version 1.3.0 --release-type stable

Release candidate:

./scripts/release/unified_release.py --version 1.3.0-rc1 --release-type rc

Release Types

Type	Example	Use Case
stable	1.3.0	Production
rc	1.3.0-rc1	Release candidate
beta	1.3.0-beta1	Beta testing
alpha	1.3.0-alpha1	Early testing

Platform Detection

./scripts/release/detect_platform.py

Supported: Joomla, Dolibarr, WordPress, Python, Node.js, Generic

Extension Packaging

./scripts/release/package_extension.py --version 1.3.0

Output: release/ProjectName-1.3.0.zip + checksums

Terraform Distribution

Deployment

Automatic:

./api/automation/bulk_update_repos.php --yes --set-standards

Manual:

cd infrastructure/terraform/repository-management
terraform apply -var="github_token=$GH_TOKEN"

Configuration Files

• infrastructure/terraform/repository-types/default-repository.tf - Structure definition
• infrastructure/terraform/repository-management/main.tf - Distribution config

Troubleshooting

Version Not Found

Error: Version not found in README.md

Fix: Ensure format is # README - ProjectName (VERSION: 04.06.00)

Permission Denied

chmod -R 755 scripts/
chmod 644 scripts/**/*.py

Failed Mid-Operation

# Check backup
ls -la .version_bump_backup/

# Rollback
cp -r .version_bump_backup/* ./

# Retry
./api/automation/detect_version_bump.py --text "Fix" --apply

Debug Mode

# Verbose output
./api/automation/detect_version_bump.py --verbose --text "..."

# Check logs
cat logs/automation/version_bump_*.json | jq '.'

Integration Patterns

Gitea Actions

name: Auto Version Bump
on:
  pull_request:
    types: [closed]
    branches: [main]

jobs:
  version-bump:
    if: github.event.pull_request.merged == true
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Apply Version Bump
        run: |
          ./api/automation/detect_version_bump.py \
            --text "${{ github.event.pull_request.body }}" \
            --apply \
            --stats

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit

if git diff --cached --name-only | grep -qE '(\.py|\.md)$'; then
    ./api/automation/detect_version_bump.py --validate || {
        echo "❌ Version inconsistency"
        exit 1
    }
fi

Best Practices

Version Management

1. Always run dry-run first
2. Review audit logs regularly
3. Keep backups for 30+ days
4. Use semantic versioning consistently

Branch Management

1. Run cleanup monthly
2. Always dry-run before delete
3. Maintain protected branch list
4. Document exceptions

Release Automation

1. Detect platform before release
2. Test packaging in non-prod
3. Verify checksums
4. Maintain release notes

Reference

Related Documentation

• Terraform Distribution Guide
• Maintenance Scripts
• Release Scripts
• Branching Strategy

External Resources

• Semantic Versioning
• Keep a Changelog
• Conventional Commits

Support

Getting Help:

1. Check this documentation
2. Review troubleshooting section
3. Check audit logs: logs/automation/*.json
4. Contact moko-platform maintainers

Reporting Issues: Include: script name, command, error message, audit log, context

---

Document Version: 1.0.0
Next Review: 2026-03-10
Maintainer: moko-platform Team

Repo: moko-platform · moko-platform wiki

Field	Value
Minimum Version	04.07.00
Platform	all
Applies To	All repositories

Revision	Date	Author	Description
1.0	2026-05-08	Moko Consulting	Initial version