Skip to content

Release Flow

Jump to bottom
James Maes edited this page Mar 12, 2026 · 6 revisions

Release Flow

QQQ's release process is fully automated through CircleCI and the qqq-orb, following GitFlow principles. This guide covers the end-to-end release workflow.

For CI/CD configuration details (how to set up your .circleci/config.yml), see CI/CD Setup with qqq-orb.

Quick Links

Release Overview

QQQ uses automated CI/CD with manual release branch creation. Every push triggers the appropriate qqq-orb job based on the branch name:

graph LR
    A[Develop Branch<br/>Continuous SNAPSHOT] --> B[Release Branch<br/>Manual Creation]
    B --> C[Release Candidate<br/>Automated RC.n]
    C --> D[Main Branch<br/>Production Release]
    D --> E[Maven Central<br/>Public Distribution]

    F[Hotfix Branch<br/>Urgent Fixes] --> G[Patch Release<br/>Automated]
    G --> E

    style A fill:#e1f5fe
    style B fill:#fff3e0
    style C fill:#f3e5f5
    style D fill:#e8f5e8
    style E fill:#fce4ec
    style F fill:#fff8e1
    style G fill:#f1f8e9
Loading

Release Types

1. Development Snapshots (develop branch)

  • Trigger: Every push to develop
  • Orb job: qqq-orb/mvn_publish with branch_type: snapshot
  • Version: X.Y.Z-SNAPSHOT (calculated automatically)
  • Publishes to: Maven Central snapshots repository
  • GitHub Release: No

2. Release Candidates (release/ branches)*

  • Trigger: Push to release/X.Y branch
  • Orb job: qqq-orb/mvn_publish with branch_type: release_candidate
  • Version: X.Y.0-RC.N (increments automatically on each push)
  • Publishes to: Maven Central releases repository
  • GitHub Release: No (created when merged to main)

3. Production Releases (main branch)

  • Trigger: Merge release/X.Y into main
  • Orb job: qqq-orb/mvn_publish with branch_type: release
  • Version: X.Y.0 (stable, from git tag)
  • Publishes to: Maven Central releases repository
  • GitHub Release: Yes (auto-generated release notes)
  • Git tag: vX.Y.0 (created and pushed automatically)

4. Hotfix Releases (hotfix/ branches)*

  • Trigger: Push to hotfix/* branch, then merge to main
  • Orb job: qqq-orb/mvn_publish with branch_type: hotfix
  • Version: X.Y.(Z+1) (patch increment)
  • Publishes to: Maven Central releases repository
  • GitHub Release: Yes
  • Git tag: vX.Y.(Z+1) (created and pushed automatically)

Release Workflow

Step 1: Prepare Release

Ensure develop is green and all features for this release are merged:

git checkout develop
git pull origin develop

# Create release branch (use X.Y format, not X.Y.Z)
git checkout -b release/1.5
git push origin release/1.5

What CI does automatically:

  1. The qqq-orb's publish_release_candidate workflow triggers
  2. calculate_version.sh reads pom.xml, detects release/1.5 branch, sets version to 1.5.0-RC.1
  3. Builds, runs all tests, deploys 1.5.0-RC.1 to Maven Central

Important: The release branch must be named release/X.Y (e.g., release/1.5), not release/X.Y.Z. The patch version is always 0 for initial releases.

Step 2: Test Release Candidate

Test the RC build in a downstream project:

<dependency>
    <groupId>com.kingsrook.qqq</groupId>
    <artifactId>qqq-backend-core</artifactId>
    <version>1.5.0-RC.1</version>
</dependency>

Testing Checklist:

  • All features work as expected
  • Module integration is correct
  • No performance regression
  • Release notes are accurate

Step 3: Iterate if Needed

If issues are found, fix them on the release branch:

git checkout release/1.5
# make fixes
git commit -m "fix: resolve null pointer in query filter"
git push origin release/1.5

CI automatically builds and publishes 1.5.0-RC.2. Each push increments the RC number.

Step 4: Finalize Release

When the RC is stable, merge to main and tag:

# Merge release branch to main and create the version tag
git checkout main && git pull
git merge release/1.5
git tag v1.5.0
git push origin main v1.5.0

What CI does automatically:

  1. The v1.5.0 tag push triggers the publish_release workflow
  2. calculate_version.sh reads the tag, sets pom.xml version to 1.5.0
  3. Builds, tests, publishes 1.5.0 to Maven Central
  4. Creates GitHub Release with auto-generated notes

Important: Create the tag before pushing. The publish_release workflow is triggered by the tag push, and the version is read from the tag name.

Step 5: Post-Release Cleanup

Merge the release branch back into develop and clean up:

# Merge back into develop so develop gets any RC fixes
git checkout develop && git pull
git merge release/1.5
git push origin develop

# Delete the release branch
git branch -d release/1.5
git push origin --delete release/1.5

After the merge to develop, CI recalculates the version. If it detects the merge from a release branch, it bumps develop to 1.6.0-SNAPSHOT (next minor).

Hotfix Workflow

For critical issues in production:

# 1. Create hotfix branch from main
git checkout main && git pull
git checkout -b hotfix/1.5.1
git push origin hotfix/1.5.1

# 2. Fix the issue
git commit -m "fix: critical auth token validation bypass"
git push origin hotfix/1.5.1

CI automatically calculates version 1.5.1, builds, tests, and publishes.

# 3. When verified, merge to main and tag
git checkout main && git merge hotfix/1.5.1
git tag v1.5.1
git push origin main v1.5.1

# 4. Merge back to develop
git checkout develop && git merge hotfix/1.5.1
git push origin develop

# 5. Clean up
git branch -d hotfix/1.5.1
git push origin --delete hotfix/1.5.1

The v1.5.1 tag push triggers the publish_release workflow, which creates the GitHub Release.

Version Calculation

The qqq-orb's calculate_version.sh handles all version management. You never need to manually edit pom.xml versions.

Branch Version Pattern Example
develop X.Y.Z-SNAPSHOT 1.5.0-SNAPSHOT
release/X.Y (1st push) X.Y.0-RC.1 1.5.0-RC.1
release/X.Y (Nth push) X.Y.0-RC.N 1.5.0-RC.3
main (tagged) X.Y.Z 1.5.0
hotfix/* X.Y.(Z+1) 1.5.1
feature/* X.Y.Z-name-hash-SNAPSHOT 1.5.0-new-widget-abc1234-SNAPSHOT

Quality Gates

CI enforces these automatically on every build:

  • Compilation: Maven build must succeed
  • Tests: All tests must pass
  • Coverage: 80% instruction, 95% class minimum (Jacoco)
  • Style: Checkstyle validation
  • Security (optional): Gitleaks, Semgrep, OWASP scanning

No artifacts are published if any gate fails.

Troubleshooting

Common Issues

  • Version not calculating correctly: Ensure branch name matches release/X.Y format exactly (not release/X.Y.Z)
  • Publishing failures: Check that qqq-maven-registry-credentials context has valid Sonatype and GPG credentials
  • GitHub Release not created: GITHUB_TOKEN must be set as a project env var; only happens on release and hotfix branch types
  • Orb version not updating: Reruns use the old orb version; trigger a new pipeline instead

Rollback

If a release has critical issues:

# Option 1: Hotfix (preferred)
git checkout main && git pull
git checkout -b hotfix/1.5.1
# fix the issue, push, merge (see Hotfix Workflow above)

# Option 2: Revert the merge commit
git checkout main
git revert -m 1 <merge-commit-sha>
git push origin main

See Also

QQQ - Metadata-driven application framework for Java.

GitHub | Maven Central | License (AGPL-3.0)

QQQ Wiki

Getting Started

Architecture

Development

QBits

Features

Mobile

Releases

Contributing

Reference

Clone this wiki locally