Skip to content

Release Process

Jump to bottom
George Gastaldi edited this page Oct 24, 2024 · 10 revisions

This wiki page is intended to document the Release Process of the SmallRye Projects.

Github Actions

Github Actions provides a way to execute Workflows on Github Events. These events can trigger code builds, releases or automate any other action related to the repository.

Release Process

Ideally, the Release Process should follow these steps:

  • A committer triggers a Release
  • The Release needs approval from other committers
  • The Release must pass the following checks:
    • The branch being released must have a passing build
    • A Milestone with the version being released must exist
    • The Milestone being released must have all Issues closed, and Pull Requests merged
    • The Sonar Quality Gates must be passing
  • Set the version to be released
  • Tag the code being released
  • Publish binaries to Maven Central
  • Create the Release change log
  • Publish the change log in a GitHub Release
  • Leave the code ready for the subsequent development iteration

Pull Request model

Opening a Pull Request starts the release process. The trick is to keep a file in the repository with the project version that can be modified and committed. This will signal the Release Process Workflow that a release should be performed and which version to release. The branch of the commit indicates which branch must be used for the release.

The Pull Request allows you to implement and perform all the checks as part of the Pull Request status. The built-in review and approval features allow other committers to approve or veto the release.

Implementation

This requires some configuration and setup, but publishing the release once done should be straightforward.

Requirements

  • In the repository Settings go to Rules and then Rulesets; Add a ruleset branch protection in for main:
    • Add the SmallRye CI Releases app to the Bypass list
    • Set Restrict deletions
    • Set Require linear history
    • Set Require signed commits
    • Set Require a pull request before merging
      • Set Require approvals (at least one reviewer)
      • Set Dismiss stale pull request approvals when new commits are pushed
      • Set Require review from Code Owners
      • Set Require approval of the most recent reviewable push
      • Set Require conversation resolution before merging
    • Set Require status checks to pass before merging (add the property status checks)
      • Set Require branches to be up to date before merging
      • Set Do not require status checks on creation
      • Set Status checks that are required
        • Usually build from Github Actions or any other required workflow
    • Set Block force pushes
  • Create a project metadata file in .github/project.yml. This is used to read properties and expose them between steps:
name: SmallRye Config
release:
  current-version: 2.0.0
  next-version: 2.0.1-SNAPSHOT

This file can contain any metadata required by the project. It is used to state the current and next version for release, but it can be used for other stuff. The Project Metadata Action reads the file and exposes all its properties as output parameters to use across Github Actions Workflows steps.

Releasing

The release is split into two steps: prepare and perform. These are triggered once the Pull Request changing the .github/project.yml is merged in the main branch:

Preparing the release

  • Change the current-version and next-version properties stored in .github/project.yml, commit the file, and open a Pull Request to the branch you want to release.
  • The Pull Request must come from a branch in the origin repository. Right now, for security reasons, secrets are not propagated to forks, even for Pull Requests targeting the original repository (https://github.community/t5/GitHub-Actions/Github-Workflow-not-running-from-pull-request-from-forked/m-p/33547/highlight/true#M1555)
  • A review request will be sent to the owners set in CODEOWNERS immediately.
  • The Github Action bot will review and approve your Pull Request after a few checks (Milestone exists, issues open, non-SNAPSHOT version). If not, it will Request Changes with the fixes. The Milestone title must be the same name as the project version.
  • If all checks pass and there is an Approved Review from any code owners, then you can Merge the Pull Request.
  • The Pull Request Merge will trigger the full release.
  • The workflows read the release version and new development version from .github/project.yml and use the Maven Release Plugin to update the project and prepare the release (set release version, tag the code, set new development version, commit changes)
  • Closes the associated Milestone, generates Changelog from the Milestone issues, and creates a GitHub Release.
  • Feel free to delete the release branch.

Performing the release

  • Once the preparation step is complete, the perform-release step is triggered
  • The workflow will build the project and deploy to a local repository (using mvn deploy -DaltDeploymentRepository)
  • Then it will TAR all the contents, generate an artifact attestation and upload as a build artifact (using actions/upload)
  • Finally, it will trigger the deploy-artifacts.yml workflow in the smallrye-release repository, which will fetch this artifact, verify if the attestation is valid, check if the artifacts group ID matches the repository that requested the release, sign the artifacts, and deploy to Nexus Sonatype.

FAQ

I keep getting errors in some modules saying that -sources and -javadoc are missing, what do I do?

There are two solutions:

  1. If your module shouldn't be in central (eg. docs), exclude it from your pom.xml using a Maven profile as the example below:
    <profile>
        <id>docs</id>
        <activation>
            <property>
                <name>performRelease</name>
                <value>!true</value>
            </property>
        </activation>
        <modules>
            <module>docs</module>
        </modules>
    </profile>
  1. If your JAR contains only resources or it is meant to empty, the workaround is to add a dummy class so the missing -sources and -javadoc are generated

Resources

Clone this wiki locally