This document describes how to configure and use the Maven release plugin to publish to Sonatype.
Releases are done on an as-needed basis, and this doc applies only to OWNERS.
This does not describe the process of cherry-picking changes onto release branches.
Maintainers meet the following requirements will be able to perform automated release to maven central via Github Action job named "Maven Release":
- Has "collaborator" permission or greater access (otherwise the can't run the job manually).
- Should be in the OWNERS file.
When cutting the next major release, firstly we need to fork out a new release
branch named release-<major>
. So the release job will execute the maven
release plugin and push generated releasing commits to the release branch
if the release:prepare
process finishes successfully. Note that if we're
bumping a new patch version from an existing release branch, this step can be
omitted.
The github action job will require three manual input:
- The POM releasing version, must be a valid semver
X.Y.Z
(without "v" prefix). - The next development POM version, conventionally we should bump a patch
version from the current release version and add a
-SNAPSHOT
suffix. i.e.X.Y.(Z+1)-SNAPSHOT
. - Dry-Run: Indicating whether the release job will push the generated release commits to the release branch and actually upload the artifacts.
Filling the inputs, then click "Run" to start the job.
Note that during the release process, no commits shall be added the release branch.
After the release job successfully finishes, we're supposed to see two generated commits automatically added to the release branch:
- Bump the previous development version to the target release version.
- Bump the release version to the next development version.
And a git tag vX.Y.Z
will also be pushed on the commit (1), a GITHUB release
will also be packed on the tag.
In the end, don't forget to clarify the release notes on the GITHUB release.
You will need to have the following in place:
-
SSH keys for an account capable of pushing commits & tags to https://github.com/kubernetes-client/java. These will be used by the release plugin to push an updated pom.xml along with a tag corresponding to the release being performed. If you don't have these keys, follow this guide.
-
A Sonatype JIRA account that's been authorized to publish to
io.kubernetes:client-java
. With your credentials in-hand, place these in yoursettings.xml
(typically~/.m2/settings.xml
) config file. An example config is:
<settings>
<servers>
<server>
<id>ossrh</id>
<username>your-jira-id</username>
<password>your-jira-pwd</password>
</server>
</servers>
</settings>
- A GPG key - if you are a publisher, you should already have a copy. You will be prompted on STDIN to enter the key's passphrase during release.
There are three stages to a release explained in detail below:
Prior to publishing a release, you need to collect three release-specific pieces of information:
-
This release's version. We follow semver to determine release versions.
-
This release's changelog. This can generally be inferred from the commit history, which may need some modification to make presentable. A quick way to collect the commit history is to run
git log <last-release-tag>..HEAD --online
. -
This release's Kubernetes API compatability changes (if applicable). Generally, if this release reduces functionality with a specific version of the Kubernetes API it's worth bumping the major version number to indicate a breaking change.
File an issue with the
title Propose release <VERSION>
, and open a PR against the master
branch
with an updated changelog and compatibility matrix (if necessary). Once at
least one other
OWNER LGTMs the
PR, merge it, and close the issue.
Before we can publish to Maven Central, we need decide on our release branch.
The release branch will always be of the form release-<MAJOR>.<MINOR>
. Any
time a <MAJOR>
or <MINOR>
version number is incremented, a new release
branch needs to be created with git checkout -b release-<MAJOR>.<MINOR>
from
the branch containing the changes you want to release. If you are only
releasing bug fixes for an existing <MAJOR>.<MINOR>
release (a patch
release), you simply checkout that existing release branch git checkout release-<MAJOR>.<MINOR>
.
Now we are ready to perform the release.
Make sure there are no unstaged changes, otherwise mvn
will reject the
release. There are two commands to be run in the root directory:
-
mvn release:prepare -DdryRun=true
: This will perform a dry run of the automated SCM modifications that will performed in the next step. If everything looks OK - you're good to continue. -
mvn release:clean release:prepare release:perform
: This will first clean any staged modifications made in the prior run, commit a newpom.xml
version, tag your source with the current release, build and sign your artifacts with your GPG key, and publish the release to Maven central.
At this point, you will have an unstaged change changing the value of the
version in pom.xml
to <NEXT_RELEASE>-SNAPSHOT
. Commit this change and push
it to the upstream current release branch. This allows future development for
the next release to happen on this branch.
Finally, merge any changes in your release branch back into master by opening a PR against the main repository.
Now that the release is consumable, there are two things left to do:
-
Find the newly released tag that was pushed by
mvn release:prepare
under the tags of the client library, and click "Add release notes". Title the release version of the formMAJOR.MINOR.PATCH
, and include the changelog in the release description. -
Send an email to
[email protected]
with the subject[ANNOUNCE] kubernetes-java-client <VERSION> is released
, and include a link to the release created in step 3.1 in the message body.
Let's add entries here as we run into problems.
-
Authentication problems: Ensure your git SSH keys & JIRA account have access to https://github.com/kubernetes-client/java and the
io.kubernetes:client-java
repositories respectively. If this is the case, checkmvn release:<command>
output for complaints of malformedsettings.xml
entries. -
Undo a mistake: If you've made a mistake during a release, and the release hasn't been published, running
mvn release:clean
will unstage local changes and remove generated release configuration, returning the state of your git repo to normal.