Release Process

This document describes the complete release process for PatternFly Java, including artifact deployment to Maven Central, documentation publishing, and GitHub release creation. The release process is automated through GitHub Actions and is triggered by pushing a version tag.

For information about continuous integration and automated verification, see CI/CD Workflows. For details about the build pipeline, see Build Pipeline.

Overview

The PatternFly Java release process consists of five coordinated stages executed as GitHub Actions workflows:

1. BOM Deployment - Deploy the Bill of Materials to Maven Central
2. Maven Artifact Deployment - Deploy all library modules to Maven Central with GPG signatures
3. API Documentation Publishing - Generate and publish Javadoc to GitHub Pages
4. Showcase Publishing - Build and deploy the J2CL showcase application
5. GitHub Release Creation - Create a GitHub release with extracted changelog notes

All stages execute automatically when a version tag matching the pattern v* is pushed to the repository.

Sources: .github/workflows/release.yml1-157

Release Workflow Architecture

Sources: .github/workflows/release.yml11-157

Triggering a Release

Releases are triggered by pushing a Git tag with the v prefix to the repository. The tag name should match the semantic version in the POM files without the -SNAPSHOT suffix.

Prerequisites

Before triggering a release, ensure:

1. All tests pass in the main branch
2. The version in pom.xml31 has been updated to the release version (remove -SNAPSHOT)
3. The version in bom/pom.xml32 matches the main POM version
4. CHANGELOG.md has been updated with release notes for the new version
5. All changes are committed and pushed to the main branch

Creating and Pushing the Release Tag

The tag pattern is defined in .github/workflows/release.yml5-6 and must start with v to trigger the workflow.

Sources: .github/workflows/release.yml3-6 pom.xml31 bom/pom.xml32

BOM Deployment

The first stage deploys the Bill of Materials (BOM) to Maven Central. This must complete successfully before the main artifact deployment begins.

The BOM deployment executes in the deploy-bom job defined in .github/workflows/release.yml12-40 Key configuration:

• Working Directory: bom module .github/workflows/release.yml25-36
• Maven Command: ./mvnw --show-version --batch-mode --no-transfer-progress .github/workflows/release.yml16
• GPG Configuration: Uses pinentry loopback mode to prevent interactive prompts bom/pom.xml232-235
• Publishing Plugin: central-publishing-maven-plugin version 0.9.0 bom/pom.xml80-243
• Auto-Publish: Enabled with autoPublish=true and waitUntil=published bom/pom.xml247-248

The BOM POM is configured in the release profile at bom/pom.xml216-254 which includes:

• GPG artifact signing with maven-gpg-plugin bom/pom.xml222-239
• Central publishing with central-publishing-maven-plugin bom/pom.xml241-250

Sources: .github/workflows/release.yml12-40 bom/pom.xml216-254 bom/pom.xml80

Maven Artifact Deployment

After the BOM is successfully deployed, all PatternFly Java modules are built, signed, and deployed to Maven Central. This stage depends on deploy-bom completing successfully .github/workflows/release.yml45

Module Deployment Process

The deployment covers all modules defined in pom.xml113-126:

The deploy-patternfly job executes the following steps:

1. Package Phase - Build all modules with mvn package .github/workflows/release.yml55
2. Credential Setup - Configure Maven settings.xml with Central credentials .github/workflows/release.yml56-64
3. Deployment - Execute mvn deploy -P release .github/workflows/release.yml65

Release Profile Configuration

The release profile is defined in pom.xml483-556 and includes:

• Dependency Validation: Enforces no snapshot dependencies pom.xml492-495
• Source Attachment: Creates source JARs with maven-source-plugin pom.xml500-508
• Javadoc Attachment: Creates Javadoc JARs with maven-javadoc-plugin pom.xml512-520
• GPG Signing: Signs all artifacts with maven-gpg-plugin pom.xml524-541
• Central Publishing: Publishes to Maven Central with central-publishing-maven-plugin pom.xml543-553

The Central Publishing plugin configuration at pom.xml544-552:

publishingServerId: central
autoPublish: true
waitMaxTime: 86400
waitUntil: published

Sources: .github/workflows/release.yml42-69 pom.xml483-556 pom.xml113-126

API Documentation Publishing

The API documentation is generated using Maven Javadoc plugin and published to a separate GitHub Pages repository. This job runs independently of the deployment jobs and does not wait for them.

Documentation Build Steps

The publish-apidocs job defined in .github/workflows/release.yml71-104 executes these steps:

1. Install Graphviz - Required for dependency graph generation .github/workflows/release.yml77
2. Build BOM - Install BOM to local repository .github/workflows/release.yml86-87
3. Build Modules - Quick build with -Dquickly flag .github/workflows/release.yml88
4. Generate Dependency Graph - Using depgraph-maven-plugin .github/workflows/release.yml89
5. Copy Documentation Files - Aggregate sources from all modules .github/workflows/release.yml91-93
6. Generate Javadoc - Create HTML documentation .github/workflows/release.yml94
7. Deploy to GitHub Pages - Publish to patternfly-java/apidocs repository .github/workflows/release.yml96-104

Javadoc Configuration

The Javadoc configuration is defined in pom.xml431-453:

• Snippet Path: Demo code directory for code examples pom.xml432
• External Links: Links to Elemento, GWT, Elemental2, and other API docs pom.xml440-450
• Source Excludes: Excludes demo files from API documentation pom.xml436-438
• Detection: Automatically detects links to external libraries pom.xml434

The quick build profile skips various checks to speed up the build pom.xml465-481:

checkstyle.skip=true
editorconfig.skip=true
enforcer.skip=true
impsort.skip=true
license.skip=true
maven.javadoc.skip=true
skipTests=true

Sources: .github/workflows/release.yml71-104 pom.xml431-453 pom.xml465-481

Showcase Publishing

The showcase application is built with J2CL and Parcel, then published to GitHub Pages. This job depends on successful completion of deploy-patternfly to ensure the latest artifacts are available .github/workflows/release.yml109

Showcase Build Configuration

The showcase build uses two Maven profiles:

Showcase Profile - Activates the showcase module pom.xml558-562:

Production Profile - Optimizes J2CL compilation showcase/pom.xml223-249:

• j2cl.compilationLevel=ADVANCED_OPTIMIZATIONS showcase/pom.xml226
• j2cl.incremental=false showcase/pom.xml227
• j2cl.sourcemaps=true showcase/pom.xml228
• Executes npm run prod for Parcel bundling showcase/pom.xml237-244

J2CL Plugin Configuration

The J2CL Maven plugin is configured in showcase/pom.xml202-218:

• Compilation Level: Configurable via j2cl.compilationLevel property showcase/pom.xml205
• Source Maps: Enabled for debugging showcase/pom.xml206
• Incremental Build: Disabled for production showcase/pom.xml207
• Output File: showcase.js showcase/pom.xml208
• Output Directory: target/showcase showcase/pom.xml209

GitHub Pages Deployment

The deployment uses JamesIves/github-pages-deploy-action .github/workflows/release.yml122-130 with:

• Target Repository: patternfly-java/patternfly-java.github.io .github/workflows/release.yml125
• Branch: gh-pages .github/workflows/release.yml126
• Source Folder: ./showcase/target/showcase .github/workflows/release.yml127
• Clean Deploy: Removes all existing files .github/workflows/release.yml128
• Single Commit: Squashes history .github/workflows/release.yml130

Sources: .github/workflows/release.yml106-130 showcase/pom.xml223-249 showcase/pom.xml202-218 pom.xml558-562

GitHub Release Creation

The final stage creates a GitHub release with version information and changelog notes extracted from the CHANGELOG.md file. This job depends on successful artifact deployment .github/workflows/release.yml135

Release Creation Steps

The release job defined in .github/workflows/release.yml132-157 performs:

1. Version Extraction - Uses battila7/get-version-action to extract version from tag .github/workflows/release.yml137-139
2. Repository Checkout - Checks out the code to access CHANGELOG.md .github/workflows/release.yml140
3. Changelog Reading - Uses mindsers/changelog-reader-action to parse release notes .github/workflows/release.yml141-146
4. Release Publication - Uses softprops/action-gh-release to create the release .github/workflows/release.yml147-156

Changelog Format

The changelog follows Keep a Changelog format as specified in CHANGELOG.md5 Each version section contains:

• Version Header: ## [VERSION] - DATE CHANGELOG.md9
• Change Categories: Added, Changed, Fixed, Security, Deprecated, Removed, Upgrades CHANGELOG.md11-46
• Version Links: At the bottom of the file CHANGELOG.md714-761

Example from the changelog:

Release Configuration

The action-gh-release is configured in .github/workflows/release.yml147-156:

• Tag Name: Version from get-version-action .github/workflows/release.yml151
• Release Name: PatternFly Java {version} .github/workflows/release.yml152
• Body: Extracted changelog notes .github/workflows/release.yml153
• Draft: false .github/workflows/release.yml154
• Prerelease: false .github/workflows/release.yml155
• Discussion: Creates announcement in discussions .github/workflows/release.yml156

Sources: .github/workflows/release.yml132-157 CHANGELOG.md1-761

Manual Publishing Workflows

Two additional workflows allow manual publishing of documentation and showcase without creating a full release.

Manual API Documentation Publishing

The workflow defined in .github/workflows/apidocs.yml1-43 can be triggered manually via workflow_dispatch .github/workflows/apidocs.yml4 It performs the same steps as the release documentation publishing but can be executed at any time.

Trigger: GitHub Actions UI → "Publish API Documentation" workflow → "Run workflow"

Manual Showcase Publishing

The workflow defined in .github/workflows/showcase.yml1-35 can be triggered manually via workflow_dispatch .github/workflows/showcase.yml4 It builds and publishes the showcase independently of releases.

Trigger: GitHub Actions UI → "Publish Showcase" workflow → "Run workflow"

Key Difference: Manual showcase publishing requires installing the BOM first .github/workflows/showcase.yml24-25 since it may run against unreleased snapshot versions.

Sources: .github/workflows/apidocs.yml1-43 .github/workflows/showcase.yml1-35

Snapshot Publishing

Snapshot versions are automatically published to Maven Central after successful verification builds. This is handled by the snapshot workflow defined in .github/workflows/snapshot.yml1-49

Snapshot Workflow Trigger

The snapshot workflow is triggered by successful completion of the verify workflow .github/workflows/snapshot.yml4-6:

Snapshot Deployment Process

The workflow executes two jobs:

1. snapshot-bom - Deploys BOM snapshots .github/workflows/snapshot.yml9-28

   • Command: mvn deploy -DskipTests .github/workflows/snapshot.yml24
   • Working directory: bom .github/workflows/snapshot.yml25

2. snapshot - Deploys all module snapshots .github/workflows/snapshot.yml30-49

   • Depends on: snapshot-bom .github/workflows/snapshot.yml33
   • Command: mvn deploy -DskipTests .github/workflows/snapshot.yml46

Snapshots are deployed to the Maven Central snapshot repository configured in pom.xml72-76:

Note: Snapshot deployment does not use the release profile, so artifacts are not GPG signed and source/javadoc JARs are not attached.

Sources: .github/workflows/snapshot.yml1-49 pom.xml72-76

Required Secrets

The release workflows require the following GitHub secrets to be configured in the repository settings:

The secrets are referenced in the workflow files:

• Maven Central credentials: .github/workflows/release.yml38-69
• GPG configuration: .github/workflows/release.yml33-34
• Publishing token: .github/workflows/release.yml98-124

Sources: .github/workflows/release.yml33-124

Post-Release Steps

After the release workflow completes successfully:

1. Verify Maven Central - Check that artifacts appear at https://central.sonatype.com/search?q=g:org.patternfly

2. Verify Documentation - Confirm API docs are published at https://patternfly-java.github.io/apidocs/

3. Verify Showcase - Confirm showcase is available at https://patternfly-java.github.io/

4. Verify GitHub Release - Check the release page at https://github.com/patternfly-java/patternfly-java/releases

5. Update Version - Bump version numbers for next development cycle:

   • Update pom.xml31 to next SNAPSHOT version
   • Update bom/pom.xml32 to match
   • Update version references in README.md48
   • Commit and push changes

6. Announce Release - The GitHub release automatically creates a discussion in the announcements category .github/workflows/release.yml156

Sources: .github/workflows/release.yml156 pom.xml31 bom/pom.xml32 README.md48