This document describes the changelog management system for moko-platform, including scripts and workflows for maintaining CHANGELOG.md according to Keep a Changelog format.

Overview

The changelog management system consists of:

Scripts: Python scripts for updating and releasing versions
Workflows: Gitea Actions for automated changelog management
Format: Follows Keep a Changelog with Semantic Versioning

Scripts

update_changelog.py

Updates CHANGELOG.md by adding entries to the UNRELEASED section.

Usage:

# Add a simple entry
python3 api/maintenance/update_changelog.py --category Added --entry "New feature X"

# Add an entry with subcategory
python3 api/maintenance/update_changelog.py --category Changed --entry "Updated API" --subcategory "API"

# Display current UNRELEASED section
python3 api/maintenance/update_changelog.py --show

Categories: Added, Changed, Deprecated, Removed, Fixed, Security

Features:

Automatically creates category sections if they don't exist
Maintains proper formatting and indentation
Supports subcategories for better organization
Validates category names

release_version.py

Releases a version by moving UNRELEASED items to a versioned section, updating VERSION headers in files, and optionally creating a GitHub release.

Usage:

# Release version (updates CHANGELOG only)
python3 api/maintenance/release_version.py --version 05.01.00

# Release with custom date
python3 api/maintenance/release_version.py --version 05.01.00 --date 2026-01-15

# Release and update VERSION in all files
python3 api/maintenance/release_version.py --version 05.01.00 --update-files

# Release, update files, and create GitHub release
python3 api/maintenance/release_version.py --version 05.01.00 --update-files --create-release

# Dry run to preview changes
python3 api/maintenance/release_version.py --version 05.01.00 --update-files --create-release --dry-run

Features:

Validates version format (XX.YY.ZZ)
Moves UNRELEASED content to new version section
Updates VERSION header in all repository files
Creates GitHub releases with extracted notes
Supports dry-run mode for testing

Workflows

Update Changelog Workflow

File: .gitea/workflows/changelog_update.yml

Trigger: Manual workflow dispatch

Purpose: Add entries to CHANGELOG.md UNRELEASED section via Gitea Actions UI

Inputs:

category: Changelog category (Added/Changed/Deprecated/Removed/Fixed/Security)
entry: Entry text
subcategory: Optional subcategory/subheading

Process:

Runs update_changelog.py script
Creates a Pull Request with changes
Labels PR with documentation and automated

Usage:

Go to Actions → Update Changelog
Click "Run workflow"
Fill in the form
Review and merge the created PR

Version Release Workflow

File: .gitea/workflows/version_release.yml

Trigger: Manual workflow dispatch

Purpose: Release a new version by moving UNRELEASED items, updating files, and creating GitHub release

Inputs:

version: Version number in XX.YY.ZZ format
date: Optional release date (defaults to today)
update_files: Whether to update VERSION in all files
create_release: Whether to create GitHub release

Process:

Validates version format
Releases version in CHANGELOG.md
Updates VERSION headers in all files (if enabled)
Commits changes
Creates Pull Request for review
Creates GitHub release after PR merge (if enabled)

Usage:

Go to Actions → Release Version
Click "Run workflow"
Enter version number (e.g., 05.01.00)
Select options (update files, create release)
Review and merge the created PR
GitHub release is created automatically

Changelog Format

Structure

# Changelog

## [UNRELEASED]

## [05.01.00] - 2026-01-15
### Added
- New feature description

### Changed
- Change description

### Security
- Security improvement

## [05.00.00] - 2026-01-04
...

Best Practices

Be Specific: Describe what changed and why
User-Focused: Write from user's perspective
Group Related: Use subcategories for related changes
Link Issues: Reference issue/PR numbers when relevant
Keep Updated: Add entries as changes are made

Version Format

Versions follow the format: XX.YY.ZZ

XX: Major version (breaking changes)
YY: Minor version (new features, backward compatible)
ZZ: Patch version (bug fixes)

Examples: 05.00.00, 05.01.00, 05.01.01

Integration with Development Workflow

During Development

Make code changes

Add changelog entry using script or workflow:

python3 api/maintenance/update_changelog.py --category Added --entry "Feature description"

Commit both code and changelog changes

For Releases

Ensure all changes are in UNRELEASED section
Run version release workflow:
- Actions → Release Version
- Enter version number
- Enable "Update files" and "Create release"
Review the created PR
Merge PR to complete release
GitHub release is created automatically

Manual Release (Alternative)

# 1. Release version
python3 api/maintenance/release_version.py --version 05.01.00 --update-files

# 2. Commit changes
git add .
git commit -m "release: version 05.01.00"

# 3. Create GitHub release
python3 api/maintenance/release_version.py --version 05.01.00 --create-release

# 4. Push changes
git push origin main

File VERSION Headers

All files with version headers are automatically updated during release:

VERSION: 04.06.00

Supported file types:

Markdown (.md)
Python (.py)
YAML (.yml, .yaml)
Text (.txt)

GitHub Release Creation

When --create-release is used, the script:

Extracts release notes from CHANGELOG.md for the version
Creates a Git tag (e.g., v05.01.00)
Creates GitHub release with:
- Tag name: v{version}
- Title: Release {version}
- Notes: Extracted from CHANGELOG.md

Requires gh CLI to be installed and authenticated.

Troubleshooting

UNRELEASED Section Not Found

Ensure CHANGELOG.md has an ## [UNRELEASED] heading.

Version Format Error

Use XX.YY.ZZ format (e.g., 05.01.00, not 5.1.0).

GitHub Release Failed

Ensure gh CLI is installed: gh --version
Authenticate: gh auth login
Check repository permissions

File Update Issues

Ensure files have VERSION headers in correct format
Check file permissions
Review dry-run output first

Examples

Example 1: Add New Feature

# Add to UNRELEASED
python3 api/maintenance/update_changelog.py \
  --category Added \
  --entry "Support for custom themes" \
  --subcategory "UI"

# View changes
python3 api/maintenance/update_changelog.py --show

Example 2: Release Minor Version

# Release 05.01.00
python3 api/maintenance/release_version.py \
  --version 05.01.00 \
  --update-files \
  --create-release

Example 3: Security Update

# Add security entry
python3 api/maintenance/update_changelog.py \
  --category Security \
  --entry "Fix XSS vulnerability in user input"

# Release patch version
python3 api/maintenance/release_version.py \
  --version 05.00.01 \
  --update-files \
  --create-release

References

Metadata

Document Version: 05.00.00 Last Updated: 2026-01-04 Status: Active

Revision History

Version	Date	Description
05.00.00	2026-01-04	Initial changelog management system documentation

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