Skip to content

Release Logistics

Jump to bottom
Robin Keskisärkkä edited this page Oct 22, 2024 · 4 revisions

Release Logistics

General development work is performed on feature branches, which are merged in to the main branch using pull requests (PRs). All feature branches should update CHANGELOG.md (see details below) to ensure release documentation is accurate and complete.

Preparing for a new release

When preparing for a new release, follow the steps below. All release branches should follow the pattern release/major.minor.patch and are feature frozen — only minor bug fixes are allowed.

  1. Merge all PRs that should be part of the new release. Ensure that no critical features are left out.
  2. Create and switch to a new release branch, following the naming convention release/<version>:
git checkout -b release/v1.0.0
git push --set-upstream origin release/v1.0.0
  1. Update the version number on the release branch:
mvn versions:set -DnewVersion=1.0.0 -DgenerateBackupPoms=false
git add **/pom.xml
git commit -m "bump up version to v1.0.0"
git push
  1. Review and update CHANGELOG.md in the root directory based on the merged PRs since the last release. Note that the changelogs are intended for humans, not machines, and the same types of changes should be grouped. Changes should be grouped by type (e.g., Added, Changed, Fixed), using the Keep a Changelog format. Example:
# Changelog
All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and
this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [unreleased]
### Added
- Support for operator y.

## [v1.0.0] - 2024-10-03

### Changed
- Refactored the query optimization algorithm.
  1. Tag and push the release branch to GitHub:
git tag -a v1.0.0 -m "Release version v1.0.0"
git push origin v1.0.0
  1. In the GitHub UI, open a PR for the release branch and ensure that it is merged into main.
  2. Pull the latest changes from main and prepare the binaries:
git checkout main
git pull 
mvn clean package && mvn package -pl hefquin-service -P build-war -am
  1. Prepare the distribution (dist/) folder:
mkdir -p ./dist/libs
cp ./hefquin-cli/target/hefquin-cli-1.0.0.jar ./dist/libs
cp -r ./bin ./dist && cp -r ./bat ./dist
zip -r dist.zip ./dist
  1. In the GitHub UI, go to the Releases section and click Draft a new release. Use the version number as the release title (e.g., v1.0.0) and include the relevant parts of the changelog as the release notes. Attach the following binaries: hefquin-service/target/hefquin-service-1.0.0.war and dist.zip.
  2. Increase the version number beyond the version of the release.
git checkout -b snapshot/v1.0.1-SNAPSHOT
mvn versions:set -DnewVersion=1.0.1-SNAPSHOT -DgenerateBackupPoms=false
git add **/pom.xml
git commit -m "bump up version beyond v1.0.0"
git push --set-upstream origin snapshot/v1.0.1-SNAPSHOT
  1. In the GitHub UI, open a PR for the snapshot-version branch and ensure that it is merged into main.

Docker Image and Maven Library Publishing

To enhance the integration and deployment processes, both a Maven library and a Docker image are automatically built and published with each new release. The corresponding GitHub Actions are specified in ??? (for the Maven libraries) and in .github/workflows/docker.yml (for the Docker images).

Docker image

The Docker images are hosted on GitHub Container Registry (ghcr.io), making it easy to pull the latest version. For example:

docker pull ghcr.io/liusemweb/hefquin:latest

Publish to Maven Central

# Linux
sudo apt update
sudo apt install gnupg

# Mac
# install
brew install gnupg pinentry-mac
# make dir and change permissions
mkdir ~/.gnupg
chmod 700 ~/.gnupg
# restart gpg-agent
killall gpg-agent
# fixes issue with asking for passphrase securely
echo "pinentry-program $(brew --prefix)/bin/pinentry-mac" > ~/.gnupg/gpg-agent.conf

It may also be necessary to add export GPG_TTY=$(tty) to ~/.bash_profile and source it:

source ~/.bash_profile
  • Generate GPG key and publish it to a keyserver:
gpg --gen-key

gpg --list-keys
pub   rsa3072 2021-06-23 [SC] [expires: 2023-06-23]
      CA925CD6C9E8D064FF05B4728190C4130ABA0F98
uid           [ultimate] Central Repo Test <[email protected]>
sub   rsa3072 2021-06-23 [E] [expires: 2023-06-23]

gpg --keyserver hkp://keyserver.ubuntu.com --send-keys CA925CD6C9E8D064FF05B4728190C4130ABA0F98
  • Generate a portal token for publishing. Go to https://central.sonatype.com/account and click the button to generate a user token. Add the server settings shown to your ~/.m2/settings.xml file:
<settings>
  ...
  <server>
    <id>central</id>
    <username>...</username>
    <password>...</password>
  </server>
  ...
</settings>

If settings.xml doesn't exist, you need to create it.

  • You should now be ready to publish using the Maven Plugin. The following pom.xml will generate Javadoc, create sources attachments, handle GPG signing, create the bundles, and generate the checksum files:
<build>
  <plugins>
    <plugin>
      <groupId>org.sonatype.central</groupId>
      <artifactId>central-publishing-maven-plugin</artifactId>
      <version>0.6.0</version>
      <extensions>true</extensions>
      <configuration>
        <publishingServerId>central</publishingServerId>
      </configuration>
    </plugin>

    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-gpg-plugin</artifactId>
      <version>1.5</version>
      <executions>
        <execution>
          <id>sign-artifacts</id>
          <phase>verify</phase>
          <goals>
            <goal>sign</goal>
          </goals>
        </execution>
      </executions>
    </plugin>

    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-source-plugin</artifactId>
      <version>2.2.1</version>
      <executions>
        <execution>
          <id>attach-sources</id>
          <goals>
            <goal>jar-no-fork</goal>
          </goals>
        </execution>
      </executions>
    </plugin>

    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-javadoc-plugin</artifactId>
      <version>2.9.1</version>
      <executions>
        <execution>
          <id>attach-javadocs</id>
          <goals>
            <goal>jar</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>
  • Run mvn deploy. Once the process succeeds, visit your account at https://central.sonatype.com/ and click the button to publish or drop. Publishing generally takes 10-30 minutes but can sometimes take several hours.
Clone this wiki locally