Release Process

Release Process

This is a description of the release process. This process can currently be executed by:

• Peter Kriens (primary) @pkriens
• BJ Hargrave @bjhargrave
• Neil Bartlett @njbartlett
• Raymond Auge @rotty3000

Credentials

• OSS Nexus Sonatype – You need to ask for an account via JIRA. Use a user token created via Profile. These credentials are expected to be in ~/.bnd/connection-settings.xml

<server>
   <id>https://oss.sonatype.org</id>
   <username>USERNAMETOKEN</username>
   <password>USERPASSWORDTOKEN</password>
   <verify>false</verify>
   <trust></trust>
</server>

• JFrog – BJ or Peter can create you an account. Both are admins on the JFrog repo.
• Github – You need an account n Github
• Eclipse – You need an account on Eclipse Marketplace

Binary Repos

The binary repositories are hosted on JFrog Artifactory https://bndtools.jfrog.io/bndtools (JFROG). We use the following repos:

Repository	Description
libs-release-local	Bnd binary releases
libs-snapshot-local	Continuous integration of all snapshots binaries
update-latest	A virtual P2 repository on the libs-release-local latest version and prior versions
update-rc	A virtual P2 repository on the libs-release-local latest release candidates
update-snapshot	A virtual P2 repository on the libs-snapshot-local latest master builds
bnd-build	A maven repository providing certain build dependencies including the Eclipse version used to compile Bndtools
bnd-test-p2	A virtual P2 repository used in testing P2 repository support in the build

The update-* virtual P2 repository configurations must be updated for each release to reference the proper version of the org.bndtools.p2 artifact which contains the P2 repository contents.

On OSS Sonatype there is a staging repository (STAGING) created to get the artifacts on Maven Central after a successful release process is done on JFROG. This is a partly manual process.

Github Repository

All code is stored on Github in https://github.com/bndtools/bnd (BNDREPO). The normal development takes place on the master branch. Changes are merged via PRs. PRs are automatically built with Github Actions for verification but do not release binaries. A commit on master is automatically released to libs-snapshot-local for any successful build. A commit on the next branch is also released to the libs-snapshot-local repository for a release candidate (RC) but to libs-release-local for a final release.

Summary

This process describes the steps to go from V1 to V2, where V1 and V2 are valid OSGi versions with a MAJOR.MINOR.MICRO for (no qualifier). For example, V1 could be 5.1.0. This release process is not an atomic process, it can take a few weeks. During these weeks, a number of release candidates (RCx) are provided for the users to test against.

First, the master and next branch are prepared for a release cycle. The master branch is moved from V1-SNAPSHOT to V2-SNAPSHOT while the next branch still uses the version V1-SNAPSHOT. The branches are properly tagged and build, this is detailed later in a checklist. Their build output will go to libs-snapshot-local but master will now build a new snapshot version V2-SNAPSHOT and next will build the V1-SNAPSHOT.

During this period fixes are being made on master. If these fixes are deemed crucial enough to include in the current release cycle then they are cherry picked on next. In principle, about once every other week a new release candidate is made available for the end users.

For P2 users (Bndtools), a virtual P2 repository is available for master on update-snapshot and for next on update-rc.

Every new RC is properly tagged in BNDREPO from the next branch with V1.RC1, V1.RC2, etc.

At the big day when the last RCx has been approved, the next branch is adjusted to not generate a snapshot but an actual release without the SNAPSHOT modified. The branch is adjusted to generate V1, tagged and pushed. With the Github actions workflow, this will build the next branch in libs-release-local. After this release is approved, the releaser will copy the V1 release artifacts from libs-release-local to STAGING, while properly signing the files. STAGING is then closed and, if no errors are detected, released to Maven Central via the Sonatype Nexus.

Classic branch

We're maintaining a classic branch that is similar to master. Its purpose is to provide the runtime libraries on Java 1.8; it does not support the plugins. It will only be updated on special request and/or if we find very security issues.

The release cycle is identical as described in the next section where the function of the master branch is replaced by the classic branch and the steps to update plugins and other artifacts except the bundles are skipped.

Preparation First Release Candidate

Make sure master is fully committed and it builds properly.

git checkout master
git pull

Set next branch to state of master branch.

git branch --force next master

• In cnf/build.bnd change base.version to V2.
• Update biz.aQute.bndlib/src/aQute/bnd/osgi/About.java to add V2 and change CURRENT to point to the new version. The package version in biz.aQute.bndlib/src/aQute/bnd/osgi/package-info.java will need bumping as a result.
• Update maven-plugins/bnd-plugin-parent/pom.xml, in the <properties> element from <revision>V1-SNAPSHOT</revision> to <revision>V2-SNAPSHOT</revision>.
• Update gradle-plugins/README.md, replace V1 to V2. (Multiple times!)
• Update gradle-plugins/gradle.propertiesfrom bnd_version: V1-SNAPSHOT to bnd_version: V2-SNAPSHOT.
• Create biz.aQute.bndlib/src/aQute/bnd/build/V2.bnd file for the V2 version and set the __versiondefaults__ property in it to V2. Make sure to copy the previous content!

Build master and push:

git add .
git commit -m "build: Start V2 stream"
git tag -s V2.DEV
./gradlew clean :gradle-plugins:clean
./mvnw --file=maven-plugins clean
./gradlew :build
./gradlew :gradle-plugins:build
./mvnw --file=maven-plugins install
git push origin master V2.DEV

You can look at a sample PR

• Create a new V2 wiki Changes in V2 page, e.g. https://github.com/bndtools/bnd/wiki/Changes-in-V2. Don't forget to add this to the wiki home page.

• Update JFROG for V2.

  • The update-snapshot P2 repository must be changed to point to the new SNAPSHOT P2 artifact.
  • Make sure the Local Repository is libs-snapshot-local and the Path Suffix is org/bndtools/org.bndtools.p2/V2-SNAPSHOT/org.bndtools.p2-V2-SNAPSHOT.jar!.
  • The *P2 Repository does not have to be set

Prepare the next branch.

git checkout next

In the paragraphs below, RC1 can be any desired Maven version qualifier.

• Update gradle.properties: Set bnd_version=[V1-RC,V2). For example, bnd_version=[6.1.0-RC,6.2). This locks down to the current version of the Gradle plugin used to build. RC is used without a following number.
• Update cnf/build.bnd to uncomment #-snapshot: and change to -snapshot: RC1.
• Update maven-plugins/bnd-plugin-parent/pom.xml to replace -SNAPSHOT with -RC1 in the <properties> element, <revision>V1-SNAPSHOT</revision>: <revision>V1-RC1</revision>.
• Update gradle-plugins/gradle.properties to replace -SNAPSHOT with -RC1 in bnd_version: V1-SNAPSHOT: bnd_version: V1-RC1.

git add .
git commit -m "build: Build Release V1.RC1"
git tag -s V1.RC1
git push --force origin next V1.RC1

• Update JFROG for the build. The update-rc P2 repository must be changed to point to the RC P2 artifact.

  • Make sure to remove all of the previous releases.
  • Add Local Repository to libs-release-local and Path Suffix to org/bndtools/org.bndtools.p2/V1-RC1/org.bndtools.p2-V1-RC1.jar!.

• Verify that that the Wiki changes are updated. The following command is useful to see the changes since the last release.

git shortlog V1.DEV..next --no-merges

RC2...

When there are changes on master that should be incorporated on the next release candidate they should be cherry picked on next.

git checkout next
git cherry-pick ...

• Update cnf/build.bnd to change -snapshot: RC1 to -snapshot: RC2.
• Update maven-plugins/bnd-plugin-parent/pom.xml to replace -RC1 with -RC2 in <revision>V1-RC1</revision>: <revision>V1-RC2</revision>.
• Update gradle-plugins/gradle.properties to replace -RC1 with -RC2 in bnd_version: V1-RC1: bnd_version: V1-RC2.

git add .
git commit -m "build: Build Release V1.RC2"
git tag -s V1.RC2
git push origin next V1.RC2

• Update JFROG for the build. The update-rc P2 repository must be changed to point to the RC P2 artifact. local://libs-release-local/org/bndtools/org.bndtools.p2/V1-RC2/org.bndtools.p2-V1-RC2.jar!. Make sure not to remove any of the previous V1 RC releases.
• Verify that that the Wiki changes are updated

git shortlog V1.DEV..next --no-merges

Release

• Update cnf/build.bnd to change -snapshot: RCx to -snapshot: (empty value).
• Update maven-plugins/bnd-plugin-parent/pom.xml to remove -RCx in <revision>V1-RCx</revision>: <revision>V1</revision>.
• Update gradle-plugins/gradle.properties to remove -RCx in bnd_version: V1-RCx: bnd_version: V1.

git add .
git commit -m "build: Build Release V1"
git tag -s V1
git push origin next V1

After the push, the release will be built and released into the libs-release-local repository.

Post Release

Maven Central

The next step is to sign and publish the release on Maven Central.

bnd nexus --url https://oss.sonatype.org/service/local/staging/deploy/maven2/ sign --from https://bndtools.jfrog.io/bndtools/libs-release-local/ --include "/V1/?" --xclude "/biz.aQute.remote.test."

The --include option must use the version being released. If you want to use a gpg key other than the default key, add a --key option after sign to specify the key ID to use. You can also specify the connections settings to use with the --settings option after nexus. For example, assuming the environment variables REPOSITORY_USERNAME and REPOSITORY_PASSWORD are set to your OSS Nexus Sonatype credentials,:

bnd --trace nexus --url https://oss.sonatype.org/service/local/staging/deploy/maven2/ --settings "server;id=https://oss.sonatype.org;username=${REPOSITORY_USERNAME};password=${REPOSITORY_PASSWORD}" sign --key 59CF9EAC --from https://bndtools.jfrog.io/bndtools/libs-release-local/ --include "/6.0.0/?" --xclude "/biz.aQute.remote.test."

• Verify the Maven Nexus repos on https://oss.sonatype.org in the staging repositories. There will be a staging repository for bizaqute and for orgbndtools since we use two group ids.
• Close each repository.
• Release each repository.

GitHub Release

Do this after the release is published to Maven Central so dependabot does not send out PRs against the new version before it is available from Maven Central.

Go to https://github.com/bndtools/bnd/releases/tag/V1 and create a GitHub Release for the V1 tag. Set the release title to

Bnd/Bndtools V1

and set the description to include a link the the release wiki page

See [Release Notes](https://github.com/bndtools/bnd/wiki/Changes-in-V1).

Workspace repo

We need to create a branch in the https://github.com/bndtools/workspace repo which holds the workspace template for the just released version of Bndtools. The name of the branch is the major.minor version of the release.

Update JFROG P2 repository

The update-latest P2 repository must be updated to add the new release P2 artifact. local://libs-release-local/org/bndtools/org.bndtools.p2/V1/org.bndtools.p2-V1.jar!.

Brain damaged UI:

• Under Local Repository, select libs-release-local
• Add the /org/bndtools/org.bndtools.p2/V1/org.bndtools.p2-V1.jar! as Path Suffix
• Verify it is added to the list below. Make sure not to remove any of the previous releases.
• DO NOT USE P2 Repository URL!
• [Save] the page. Save button is at right-bottom of page!

Publish to Gradle Plugin portal

After the release is available in Maven Central, checkout the next branch at the V1 tag. Make sure the gradle.publish.key and gradle.publish.secret Gradle properties (from the Gradle Plugin Portal) are set in ~/.gradle/gradle.properties. Then clean, build and run the publishPlugins task to publish the plugins. Make sure to use Java 17 as the build JDK.

git checkout next
cd gradle-plugins/biz.aQute.bnd.gradle
../gradlew clean
../gradlew build
../gradlew publishPlugins

Master branch baselining

After the release is available from Maven Central, we must update the baselining in the master branch.

• Update baseline.version in cnf/build.bnd to V1.
• If the V1 release added new artifacts which weren't in the previous release and that should be baselined, edit cnf/ext/baseline.mvn to add references to the new artifacts and edit the artifact's project's bnd.bnd file to add -baseline: * so that the project will now baseline.

Any baselining problems which show up in the master branch after updating the baselining information must be addressed.

Website

Edit the installation page to reflect the new release. That is, update the enhancements, known issues, and the link to the page with the changes.

Intellij OSMORC Plugin

Create a YouTrack bug report to update the version. See https://youtrack.jetbrains.com/issue/IDEA-232978

Brew

Brew is automatically handled, it updates the formula when a new version in published to Maven Central!

For changes to the recipe, you need a personal access token to update brew. A personal access token can be created with: https://github.com/settings/tokens/new?scopes=gist,public_repo&description=Homebrew

export HOMEBREW_GITHUB_API_TOKEN=<personal access token>
export RELEASE=V1
brew bump-formula-pr --url="https://search.maven.org/remotecontent?filepath=biz/aQute/bnd/biz.aQute.bnd/${RELEASE}/biz.aQute.bnd-${RELEASE}.jar" bnd

Eclipse Market Place

You can edit the Eclipse Marketplace entry for Bndtools here:

https://marketplace.eclipse.org/content/bndtools-osgi-development-tool/edit

• Verify the supported platforms and Eclipse releases.
• Update the version number to V1

Adding bnd Release Documentation

• Checkout the next branch.

• cd docs

• Edit _config.yml setting the properties:

  releasename: V1
  baseurl: /releases/V1
  

  replacing V1 for the actual version

  Note: Make sure to leave baseurl unset in the master branch.

• Build the site using bundle exec jekyll build. If you don't have the Ruby Gems installed, run ./build.sh to install them and build the site.

• Checkout the master branch. This will leave the generated contents in _site in place.

• Make a new folder releases/V1.

• Copy the generated contents in _site into the new releases/V1 folder. Make sure to remove all non-.html files that are in the releases/V1 folder. Also remove the releases/V1/releases folder.

• git add releases/V1

• git restore _config.yml

• Commit and make a pull request.