Release

Release Manager

This skill guides the creation of releases and snapshots for this Gradle-based project, including publishing to Maven Central and GitHub Releases.

Prerequisites

Before publishing, ensure the user has:

1. GPG Key configured: Must have a signing key set up
2. Maven Central access: Repository secrets configured:

• SIGNING_IN_MEMORY_KEY: GPG private key
• SIGNING_IN_MEMORY_KEY_PASSWORD: GPG key passphrase
• MAVEN_CENTRAL_USERNAME: Maven Central username
• MAVEN_CENTRAL_PASSWORD: Maven Central password

3. Write permissions: Must be a maintainer of the repository

If any prerequisite is missing, inform the user and guide them to the GPG Setup Guide first.

Branch Model

This project uses a two-branch model:

• main: Stable releases (bug fixes, non-breaking changes)
• minor: Next minor version development (features)

Ask the user which type of release they want to make:

• Patch release (e.g., 1.2.3 → 1.2.4): Changes in main
• Minor release (e.g., 1.2.3 → 1.3.0): Changes in minor

Publishing a Release

Follow these steps:

Step 1: Verify Changes

Ensure all changes to be released are in the correct branch:

• Patch: main
• Minor: minor

Help the user verify with:

git checkout main  # or minor
git pull origin main  # or minor
git log --oneline -10

Step 2: Update Version

The user has two options for version management:

Option A - Manual (update code first, then tag):

1. Update version in gradle.properties:

   VERSION=1.2.3
   

2. Update gradle/build-logic/gradle.properties:

   VERSION=1.2.3
   

3. Update docs/website/package.json version field

Option B - Sync from Git tag (if tag exists first):

# Sync version files to the latest tag
make sync-version

# Review changes
git diff gradle.properties gradle/build-logic/gradle.properties docs/website/package.json

The make sync-version command runs ./sync-version-with-tag.sh which:

• Finds the latest semantic Git tag (vX.Y.Z)
• Extracts the numeric version (drops leading v)
• Updates all version targets

Step 3: Create and Push Tag

# Create annotated tag matching the pattern vX.Y.Z
git tag -a v1.2.3 -m "Release version 1.2.3"

# Push the tag (triggers release workflow)
git push origin v1.2.3

Important: Tag must match ^v[0-9]+\.[0-9]+\.[0-9]+$ (e.g., v1.2.3)

Step 4: Monitor Workflow

1. Go to Actions tab in GitHub
2. Click on Publish Release workflow
3. Wait for completion (5-10 minutes)

The workflow will:

• Build the project
• Generate changelog from conventional commits
• Publish to Maven Central
• Create GitHub release with changelog

Publishing a Snapshot

Snapshots are useful for testing changes before a正式 release.

Automatic (Daily)

The publish-snapshot.yml workflow runs daily at 02:12 UTC.

Manual Trigger

1. Go to Actions → Publish Snapshot
2. Click Run workflow
3. Select branch (main or minor)
4. Click Run workflow

Snapshots use version with -SNAPSHOT suffix (e.g., 1.2.3-SNAPSHOT).

Troubleshooting

Release workflow failed

1. Check workflow logs in GitHub Actions
2. Common issues:

• Signing failed: GPG secrets not configured correctly
• Maven Central auth failed: Credentials expired
• Build failed: Run ./gradlew check locally first
• Version mismatch: Git tag must match code version (e.g., v1.2.3 = 1.2.3)

Version already exists

Maven Central doesn't allow overwriting releases:

1. Use new patch version (e.g., v1.2.4 instead of v1.2.3)
2. Never delete and recreate tags

Snapshot not updating

Snapshots can be cached. Force update:

./gradlew build --refresh-dependencies

Release Checklist

Before publishing, verify:

• All tests pass locally (./gradlew check)
• Version updated in build files
• CHANGELOG.md updated (if maintained)
• GPG key valid and not expired
• Maven Central credentials current
• Tag follows vX.Y.Z format
• Working on correct branch (main for patches, minor for features)

Commands Reference

# Sync version from latest Git tag
make sync-version

# Verify current version
cat gradle.properties | grep VERSION

# Run all checks before release
./gradlew check

# Create annotated tag
git tag -a v1.2.3 -m "Release v1.2.3"

# Push tag (triggers release)
git push origin v1.2.3

See Also

• Release Process Documentation
• GPG Setup Guide
• GitHub Workflows

Converted and distributed by TomeVault — claim your Tome and manage your conversions.