Skip to content

Commit c7d5f2a

Browse files
author
Lars Wander
committed
Document release process using maven-release-plugin
1 parent ff1562b commit c7d5f2a

File tree

2 files changed

+156
-3
lines changed

2 files changed

+156
-3
lines changed

‎kubernetes/RELEASES.md

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# Deploy to Maven release process
2+
3+
This document describes how to configure and use the [Maven release
4+
plugin](http://maven.apache.org/maven-release/maven-release-plugin) to publish
5+
to [Sonatype](http://central.sonatype.org/).
6+
7+
Releases are done on an as-needed basis, and this doc applies only to
8+
[OWNERS](https://github.com/kubernetes-client/java/blob/master/OWNERS).
9+
10+
This does _not_ describe the process of cherry-picking changes onto release
11+
branches.
12+
13+
## One time setup
14+
15+
You will need to have the following in place:
16+
17+
1. SSH keys for an account capable of pushing commits & tags to
18+
https://github.com/kubernetes-client/java. These will be used by the release
19+
plugin to push an updated pom.xml along with a tag corresponding to the
20+
release being performed. If you don't have these keys, follow [this
21+
guide](https://help.github.com/articles/connecting-to-github-with-ssh/).
22+
23+
2. [A Sonatype JIRA
24+
account](https://issues.sonatype.org/secure/Signup!default.jspa) that's been
25+
authorized to publish to `io.kubernetes:client-java`. With your credentials
26+
in-hand, place these in your `settings.xml` (typically
27+
`~/.m2/settings.xml`) config file. An example config is:
28+
```xml
29+
<settings>
30+
<servers>
31+
<server>
32+
<id>ossrh</id>
33+
<username>your-jira-id</username>
34+
<password>your-jira-pwd</password>
35+
</server>
36+
</servers>
37+
</settings>
38+
```
39+
40+
3. A GPG key (specifics TBD) __TODO(lwander)__
41+
42+
## Doing a release
43+
44+
There are three stages to a release explained in detail below:
45+
46+
### 1. Collect requirements and propose your release
47+
48+
Prior to publishing a release, you need to collect three release-specific pieces
49+
of information:
50+
51+
1. This release's version. We follow [semver](http://semver.org/) to determine
52+
release versions.
53+
54+
2. This release's changelog. This can generally be inferred from the commit
55+
history, which may need some modification to make presentable. A quick way
56+
to collect the commit history is to run
57+
`git log <last-release-tag>..HEAD --online`.
58+
59+
3. This release's Kubernetes API compatability changes (if applicable).
60+
Generally, if this release reduces functionality with a specific version of
61+
the Kubernetes API it's worth bumping the major version number to indicate a
62+
breaking change.
63+
64+
File an [issue](https://github.com/kubernetes-client/java/issues) with the
65+
title `Propose release <VERSION>`, and open a PR against the `master` branch
66+
with an updated changelog and compatibility matrix (if necessary). Once all
67+
[OWNERS](https://github.com/kubernetes-client/java/blob/master/OWNERS) LGTM the
68+
PR, merge it, and close the issue.
69+
70+
### 2. Publish the release to Maven Central
71+
72+
Before we can publish to Maven Central, we need decide on our release branch.
73+
74+
The release branch will always be of the form `release-<MAJOR>.<MINOR>`. Any
75+
time a `<MAJOR>` or `<MINOR>` version number is incremented, a new release
76+
branch needs to be created with `git checkout -b release-<MAJOR>.<MINOR>` _from
77+
the branch containing the changes you want to release_. If you are only
78+
releasing bug fixes for an existing `<MAJOR>.<MINOR>` release (a patch
79+
release), you simply checkout that existing release branch `git checkout
80+
release-<MAJOR>.<MINOR>`.
81+
82+
Now we are ready to perform the release.
83+
84+
Make sure there are no unstaged changes, otherwise `mvn` will reject the
85+
release. There are two commands to be run in the root directory:
86+
87+
1. `mvn release:prepare -DdryRun=true`: This will perform a dry run of the
88+
automated SCM modifications that will performed in the next step. If
89+
everything looks OK - you're good to continue.
90+
91+
2. `mvn release:clean release:prepare release:perform`: This will first clean
92+
any staged modifications made in the prior run, commit a new `pom.xml`
93+
version, tag your source with the current release, build and sign your
94+
artifacts with your GPG key, and publish the release to Maven central.
95+
96+
At this point, you will have an unstaged change changing the value of the
97+
version in `pom.xml` to `<NEXT_RELEASE>-SNAPSHOT`. Commit this change and push
98+
it to the upstream _current_ release branch. This allows future development for
99+
the next release to happen on this branch.
100+
101+
### 3. Release announcements
102+
103+
Now that the release is consumable, there are two things left to do:
104+
105+
1. Find the newly released tag that was pushed by `mvn release:prepare` under
106+
the [tags](https://github.com/kubernetes-client/java/tags) of the client
107+
library, and click "Add release notes". Title the release version of the form
108+
`MAJOR.MINOR.PATCH`, and include the changelog in the release description.
109+
110+
2. Send an email to `[email protected]` with the subject
111+
`[ANNOUNCE] kubernetes-java-client <VERSION> is released`, and include a
112+
link to the release created in step 3.1 in the message body.
113+
114+
## Troubleshooting
115+
116+
Let's add entries here as we run into problems.
117+
118+
* **Authentication problems**: Ensure your git SSH keys & JIRA account have
119+
access to https://github.com/kubernetes-client/java and the
120+
`io.kubernetes:client-java` repositories respectively. If this is the case,
121+
check `mvn release:<command>` output for complaints of malformed
122+
`settings.xml` entries.
123+
124+
* **Undo a mistake**: If you've made a mistake during a release, and the
125+
release hasn't been published, running `mvn release:clean` will unstage local
126+
changes and remove generated release configuration, returning the state of
127+
your git repo to normal.

‎kubernetes/pom.xml

Lines changed: 29 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,10 @@
99
<url>https://github.com/swagger-api/swagger-codegen</url>
1010
<description>Swagger Java</description>
1111
<scm>
12-
<connection>scm:git:[email protected]:swagger-api/swagger-codegen.git</connection>
13-
<developerConnection>scm:git:[email protected]:swagger-api/swagger-codegen.git</developerConnection>
14-
<url>https://github.com/swagger-api/swagger-codegen</url>
12+
<connection>scm:git:[email protected]:kubernetes-client/java.git</connection>
13+
<developerConnection>scm:git:[email protected]:kubernetes-client/java.git</developerConnection>
14+
<url>https://github.com/kubernetes-client/java</url>
15+
<tag>client-java-1.3</tag>
1516
</scm>
1617
<prerequisites>
1718
<maven>2.2.0</maven>
@@ -34,6 +35,17 @@
3435
</developer>
3536
</developers>
3637

38+
<distributionManagement>
39+
<snapshotRepository>
40+
<id>ossrh</id>
41+
<url>https://oss.sonatype.org/content/repositories/snapshots</url>
42+
</snapshotRepository>
43+
<repository>
44+
<id>ossrh</id>
45+
<url>https://oss.sonatype.org/service/local/staging/deploy/maven2/</url>
46+
</repository>
47+
</distributionManagement>
48+
3749
<build>
3850
<plugins>
3951
<plugin>
@@ -66,6 +78,20 @@
6678
</execution>
6779
</executions>
6880
</plugin>
81+
<plugin>
82+
<groupId>org.apache.maven.plugins</groupId>
83+
<artifactId>maven-release-plugin</artifactId>
84+
<version>2.5.3</version>
85+
<!--
86+
During release:perform, enable the "release" profile
87+
-->
88+
<configuration>
89+
<autoVersionSubmodules>true</autoVersionSubmodules>
90+
<useReleaseProfile>false</useReleaseProfile>
91+
<releaseProfiles>release</releaseProfiles>
92+
<goals>deploy</goals>
93+
</configuration>
94+
</plugin>
6995

7096
<!-- attach test jar -->
7197
<plugin>

0 commit comments

Comments
 (0)