Skip to content

Commit df4f7e9

Browse files
brendandburnsbrendandburns
authored
Merge pull request #49 from lwander/release-process-doc
Document release process using maven-release-plugin
2 parents ef5b3c8 + 0b5dbac commit df4f7e9

File tree

2 files changed

+156
-3
lines changed

2 files changed

+156
-3
lines changed

‎kubernetes/RELEASES.md

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
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 at
67+
least one other
68+
[OWNER](https://github.com/kubernetes-client/java/blob/master/OWNERS) LGTMs the
69+
PR, merge it, and close the issue.
70+
71+
### 2. Publish the release to Maven Central
72+
73+
Before we can publish to Maven Central, we need decide on our release branch.
74+
75+
The release branch will always be of the form `release-<MAJOR>.<MINOR>`. Any
76+
time a `<MAJOR>` or `<MINOR>` version number is incremented, a new release
77+
branch needs to be created with `git checkout -b release-<MAJOR>.<MINOR>` _from
78+
the branch containing the changes you want to release_. If you are only
79+
releasing bug fixes for an existing `<MAJOR>.<MINOR>` release (a patch
80+
release), you simply checkout that existing release branch `git checkout
81+
release-<MAJOR>.<MINOR>`.
82+
83+
Now we are ready to perform the release.
84+
85+
Make sure there are no unstaged changes, otherwise `mvn` will reject the
86+
release. There are two commands to be run in the root directory:
87+
88+
1. `mvn release:prepare -DdryRun=true`: This will perform a dry run of the
89+
automated SCM modifications that will performed in the next step. If
90+
everything looks OK - you're good to continue.
91+
92+
2. `mvn release:clean release:prepare release:perform`: This will first clean
93+
any staged modifications made in the prior run, commit a new `pom.xml`
94+
version, tag your source with the current release, build and sign your
95+
artifacts with your GPG key, and publish the release to Maven central.
96+
97+
At this point, you will have an unstaged change changing the value of the
98+
version in `pom.xml` to `<NEXT_RELEASE>-SNAPSHOT`. Commit this change and push
99+
it to the upstream _current_ release branch. This allows future development for
100+
the next release to happen on this branch.
101+
102+
### 3. Release announcements
103+
104+
Now that the release is consumable, there are two things left to do:
105+
106+
1. Find the newly released tag that was pushed by `mvn release:prepare` under
107+
the [tags](https://github.com/kubernetes-client/java/tags) of the client
108+
library, and click "Add release notes". Title the release version of the form
109+
`MAJOR.MINOR.PATCH`, and include the changelog in the release description.
110+
111+
2. Send an email to `[email protected]` with the subject
112+
`[ANNOUNCE] kubernetes-java-client <VERSION> is released`, and include a
113+
link to the release created in step 3.1 in the message body.
114+
115+
## Troubleshooting
116+
117+
Let's add entries here as we run into problems.
118+
119+
* **Authentication problems**: Ensure your git SSH keys & JIRA account have
120+
access to https://github.com/kubernetes-client/java and the
121+
`io.kubernetes:client-java` repositories respectively. If this is the case,
122+
check `mvn release:<command>` output for complaints of malformed
123+
`settings.xml` entries.
124+
125+
* **Undo a mistake**: If you've made a mistake during a release, and the
126+
release hasn't been published, running `mvn release:clean` will unstage local
127+
changes and remove generated release configuration, returning the state of
128+
your git repo to normal.

‎kubernetes/pom.xml

Lines changed: 28 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,9 @@
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>
1515
</scm>
1616
<prerequisites>
1717
<maven>2.2.0</maven>
@@ -34,6 +34,17 @@
3434
</developer>
3535
</developers>
3636

37+
<distributionManagement>
38+
<snapshotRepository>
39+
<id>ossrh</id>
40+
<url>https://oss.sonatype.org/content/repositories/snapshots</url>
41+
</snapshotRepository>
42+
<repository>
43+
<id>ossrh</id>
44+
<url>https://oss.sonatype.org/service/local/staging/deploy/maven2/</url>
45+
</repository>
46+
</distributionManagement>
47+
3748
<build>
3849
<plugins>
3950
<plugin>
@@ -66,6 +77,20 @@
6677
</execution>
6778
</executions>
6879
</plugin>
80+
<plugin>
81+
<groupId>org.apache.maven.plugins</groupId>
82+
<artifactId>maven-release-plugin</artifactId>
83+
<version>2.5.3</version>
84+
<!--
85+
During release:perform, enable the "release" profile
86+
-->
87+
<configuration>
88+
<autoVersionSubmodules>true</autoVersionSubmodules>
89+
<useReleaseProfile>false</useReleaseProfile>
90+
<releaseProfiles>release</releaseProfiles>
91+
<goals>deploy</goals>
92+
</configuration>
93+
</plugin>
6994

7095
<!-- attach test jar -->
7196
<plugin>

0 commit comments

Comments
 (0)