Yoko Release Guide

This document describes the standardized release process for Yoko.

🎯 Overview

Yoko uses a branch-based release workflow with Gradle automation. Releases are prepared in dedicated release/X.Y.Z branches on origin, tagged, and then fast-forward merged to main after verification. The process ensures:

✅ Consistent version management
✅ Isolated release preparation in dedicated branches
✅ Automated validation before release
✅ Complete release artifacts (JARs, sources, javadoc, checksums)
✅ Automated CHANGELOG generation
✅ GitHub releases with all binaries
✅ Clean fast-forward merge to main after successful release

📋 Prerequisites

Before starting a release, ensure you have:

Git - For version control
Important: All release commands explicitly use origin remote
If your default push remote is a fork, the commands will still push to origin
GitHub CLI (gh) - For creating releases
Install: https://cli.github.com/
Authenticate: gh auth login
git-cliff (optional) - For CHANGELOG generation
Install: https://git-cliff.org/docs/installation
SDKMAN (recommended) - For Java version management
Install: https://sdkman.io/

🚀 Standard Release Workflow

Step 1: Prepare Your Environment

# Initialize SDKMAN environment (if using)
sdk env

# Ensure you're on main branch with latest changes
git switch main
git pull origin main

# Verify everything is clean
git status

Step 2: Create Release Branch

Create a dedicated release branch for the new version:

# Create and push release branch to origin (replace X.Y.Z with your version)
git switch -c release/X.Y.Z
git push -u origin release/X.Y.Z

Step 3: Bump the Version

Choose the appropriate version bump (major, minor, or patch):

# Interactive version bump (recommended)
gradle bumpVersion

# Or non-interactive (for automation)
gradle bumpVersionNonInteractive -PversionBump=patch

This updates gradle.properties with the new version.

Commit the version change:

git add gradle.properties
git commit -m "chore: bump version to X.Y.Z"
git push origin release/X.Y.Z  # Always push to origin for releases

Step 4: Update CHANGELOG

Generate release notes from git commits:

gradle updateChangelog

This uses git-cliff to extract commits since the last release and updates CHANGELOG.md.

Review and commit the CHANGELOG:

# Review the changes
git diff CHANGELOG.md

# Stage only the relevant changes
git add -p CHANGELOG.md

# Commit
git commit -m "chore: update CHANGELOG for vX.Y.Z"
git push origin release/X.Y.Z  # Always push to origin for releases

Step 5: Validate Release Readiness

Run comprehensive validation checks:

gradle validateRelease

This checks: - ✓ Version format (semantic versioning) - ✓ CHANGELOG contains current version - ✓ Git working directory is clean - ✓ No existing tag for this version - ✓ No existing GitHub release - ✓ GitHub CLI is installed and authenticated - ✓ Tests have been run

Fix any issues before proceeding.

Step 6: Create the Release

Execute the complete release process:

gradle release

This will: 1. Verify all prerequisites 2. Build all release artifacts (6 modules × 3 JARs each) 3. Generate SHA-256 and SHA-512 checksums 4. Extract release notes from CHANGELOG 5. Create distribution archive 6. Create Git tag vX.Y.Z 7. Create GitHub release with all artifacts

Step 7: Verify the Release

Check GitHub Release:
Visit: https://github.com/OpenLiberty/yoko/releases
Verify all artifacts are present
Verify release notes are correct
Test Artifacts: bash # Download a JAR and verify checksum wget https://github.com/OpenLiberty/yoko/releases/download/vX.Y.Z/yoko-core-X.Y.Z.jar wget https://github.com/OpenLiberty/yoko/releases/download/vX.Y.Z/yoko-core-X.Y.Z.jar.sha256 sha256sum -c yoko-core-X.Y.Z.jar.sha256
Verify Git Tag: bash git fetch --tags git tag -l vX.Y.Z git show vX.Y.Z

Step 8: Merge to Main

Once the release is verified and tagged, merge the release branch to main using a fast-forward merge:

# Switch to main branch
git switch main
git pull origin main

# Fast-forward merge the release branch
git merge --ff-only release/X.Y.Z

# Push to origin (explicitly specify origin for releases)
git push origin main

# Optionally, delete the release branch
git branch -d release/X.Y.Z
git push origin --delete release/X.Y.Z

Note: The --ff-only flag ensures a clean fast-forward merge. If this fails, it means main has diverged from the release branch, and you should investigate before proceeding.

📦 Release Artifacts

Each release includes:

Per Module (6 modules)

{module}-{version}.jar - Main library
{module}-{version}-sources.jar - Source code
{module}-{version}-javadoc.jar - API documentation
{module}-{version}.jar.sha256 - SHA-256 checksum
{module}-{version}.jar.sha512 - SHA-512 checksum

Distribution

yoko-{version}-dist.zip - Complete distribution containing:
All JARs and checksums
LICENSE, NOTICE, README.md
CHANGELOG.md
RELEASE_NOTES.md

Release Modules

yoko-osgi - OSGi support
yoko-util - Utility classes
yoko-spec-corba - CORBA specification
yoko-rmi-spec - RMI specification
yoko-rmi-impl - RMI implementation
yoko-core - Core ORB implementation

🔧 Available Gradle Tasks

Task	Description
`bumpVersion`	Interactive version bump (major/minor/patch)
`bumpVersionNonInteractive`	Non-interactive version bump (use `-PversionBump=patch`)
`updateChangelog`	Update CHANGELOG.md using git-cliff
`validateRelease`	Comprehensive validation of release readiness
`verifyReleasePrerequisites`	Check prerequisites (tools, auth, etc.)
`assembleRelease`	Build all release artifacts
`generateReleaseNotes`	Extract release notes from CHANGELOG
`createDistribution`	Create distribution ZIP archive
`createGitHubRelease`	Create GitHub release with artifacts
`release`	Complete release process (recommended)

🔄 Version Management

Semantic Versioning

Yoko follows Semantic Versioning:

Major (X.0.0): Breaking changes
Minor (0.X.0): New features, backward compatible
Patch (0.0.X): Bug fixes, backward compatible

Development Versions

During development, builds automatically append metadata: - Format: {version}.{YYYYMMDD}_{gitHash} - Example: 1.6.1.20260416_a1b2c3d

Release Versions

Release versions use the exact version from gradle.properties: - Format: X.Y.Z - Example: 1.6.1

🔐 Security

Checksums

All artifacts include: - SHA-256: Fast, widely supported - SHA-512: More secure, recommended for verification

Verification

# Verify SHA-256
sha256sum -c artifact.jar.sha256

# Verify SHA-512
sha512sum -c artifact.jar.sha512

GitHub Signatures

All releases are signed by GitHub's release system.

🐛 Troubleshooting

"Git working directory is not clean"

Solution: Commit or stash your changes:

git status
git add .
git commit -m "your message"
# or
git stash

"Git tag vX.Y.Z already exists"

Solution: Either use a different version or delete the tag:

# Delete local tag
git tag -d vX.Y.Z

# Delete remote tag
git push origin :refs/tags/vX.Y.Z

"GitHub release vX.Y.Z already exists"

Solution: Delete the release first:

gh release delete vX.Y.Z --yes

"Version X.Y.Z not found in CHANGELOG.md"

Solution: Update the CHANGELOG:

gradle updateChangelog
git add CHANGELOG.md
git commit -m "chore: update CHANGELOG for vX.Y.Z"

"GitHub CLI (gh) not found"

Solution: Install GitHub CLI: - macOS: brew install gh - Linux: https://github.com/cli/cli/blob/trunk/docs/install_linux.md - Windows: https://github.com/cli/cli/releases

"GitHub authentication not configured"

Solution: Authenticate with GitHub:

gh auth login

🔄 Rolling Back a Release

If you need to roll back a release:

1. Delete GitHub Release

gh release delete vX.Y.Z --yes

2. Delete Git Tag

# Delete local tag
git tag -d vX.Y.Z

# Delete remote tag
git push origin :refs/tags/vX.Y.Z

3. Revert Version Changes

# Revert the version bump commit
git revert <commit-hash>

# Or manually edit gradle.properties
# Then commit the change
git add gradle.properties
git commit -m "chore: revert version to previous"
git push origin main

4. Update CHANGELOG (if needed)

Remove or update the release entry in CHANGELOG.md.

📚 Best Practices

Always run tests before releasing: bash gradle test
Use semantic versioning consistently
Keep CHANGELOG up to date with meaningful entries
Validate before releasing: bash gradle validateRelease
Test the release artifacts after publishing
Announce releases to relevant channels
Create releases from a dedicated release branch (release/X.Y.Z)
Use fast-forward merge to integrate release branch to main
Never force-push to main after a release
Delete release branches after successful merge (optional but recommended)

🎓 Quick Reference

Complete Release in 7 Commands

# 1. Create release branch
git switch -c release/X.Y.Z && git push -u origin release/X.Y.Z

# 2. Bump version
gradle bumpVersion
git add gradle.properties && git commit -m "chore: bump version to X.Y.Z" && git push origin release/X.Y.Z

# 3. Update CHANGELOG
gradle updateChangelog
git add CHANGELOG.md && git commit -m "chore: update CHANGELOG for vX.Y.Z" && git push origin release/X.Y.Z

# 4. Validate
gradle validateRelease

# 5. Release
gradle release

# 6. Verify
open https://github.com/OpenLiberty/yoko/releases

# 7. Merge to main (after verification)
git switch main && git pull origin main && git merge --ff-only release/X.Y.Z && git push origin main

📞 Support

For questions or issues with the release process:

Check this documentation
Review the troubleshooting section
Check existing GitHub issues
Create a new issue with the release label

📝 Release Checklist

Use this checklist for each release:

[ ] Environment prepared (sdk env)
[ ] On main branch with latest changes
[ ] Release branch created (release/X.Y.Z)
[ ] Version bumped in gradle.properties
[ ] CHANGELOG.md updated
[ ] All tests passing (gradle test)
[ ] Validation passed (gradle validateRelease)
[ ] Release created (gradle release)
[ ] GitHub release verified
[ ] Artifacts downloaded and checksums verified
[ ] Git tag verified
[ ] Release branch merged to main (fast-forward)
[ ] Release branch deleted (optional)
[ ] Documentation updated (if needed)
[ ] Release announced (if applicable)