-
-
Notifications
You must be signed in to change notification settings - Fork 305
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
-
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
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.
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.
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.
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.
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
changebase.version
to V2. - Update
biz.aQute.bndlib/src/aQute/bnd/osgi/About.java
to add V2 and changeCURRENT
to point to the new version. The package version inbiz.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.properties
frombnd_version: V1-SNAPSHOT
tobnd_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 isorg/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
: Setbnd_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
inbnd_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 toorg/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
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
inbnd_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
- 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
inbnd_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.
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 fororgbndtools
since we use two group ids. - Close each repository.
- Release each repository.
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).
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.
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!
. Make sure not to remove any of the previous releases.
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
After the release is available from Maven Central, we must update the baselining in the master branch.
- Update
baseline.version
incnf/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'sbnd.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.
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.
Create a YouTrack bug report to update the version. See https://youtrack.jetbrains.com/issue/IDEA-232978
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
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
-
Checkout the
next
branch. -
cd docs
-
Edit
_config.yml
setting the properties:releasename: V1 baseurl: /releases/V1
replacing
V1
for the actual versionNote: Make sure to leave
baseurl
unset in themaster
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 newreleases/V1
folder. Make sure to remove all non-.html
files that are in thereleases/V1
folder. Also remove thereleases/V1/releases
folder. -
git add releases/V1
-
git restore _config.yml
-
Commit and make a pull request.