Skip to content

Latest commit

 

History

History
205 lines (141 loc) · 6.58 KB

RELEASE.md

File metadata and controls

205 lines (141 loc) · 6.58 KB
Raw

Releasing

Prerequisites

In the following please substitute the placeholders <SOMETHING> with concrete values.

OSS Sonatype

See http://central.sonatype.org/pages/ossrh-guide.html

Signing

To configure jar signing, you need to have a gpg key.

  • Get public key ID gpg --list-keys --keyid-format SHORT
  • Export key gpg --keyring secring.gpg --export-secret-keys > ~/.gnupg/secring.gpg
  • Add the following properties to ~/.gradle/gradle.properties
signing.keyId=<KEY-ID>
signing.password=<PASSWORD>
signing.secretKeyRingFile=<HOME-DIR>/.gnupg/secring.gpg

Upload archives

Add the following properties to ~/.gradle/gradle.properties (same credentials as for https://oss.sonatype.org):

ossrhUsername=<USERNAME>
ossrhPassword=<PASSWORD>

Alternatively, you can pass the credentials as command line parameters:

./gradlew release --info -PossrhUsername=<USERNAME> -PossrhPassword=<PASSWORD>

OSS Sonatype Repository

SCM

  • Commits are coarsely granular grouped by feature/change.
  • Commits do not mix change sets of different domains/purpose.
  • Commit messages provide enough detail to extract a changelog for a new release.

Branching Model

We are following a simple git workflow/branching model:

                         master
                           |
                           |     v2.0.x
release v2.0.0 - - - - - - + - - - + 2.0.1-SNAPSHOT
                           |       |
                  bugfix1  |       |
                     |     |       |
                  PR x---->|<------+ cherry-picking bugfix1
                           |       |
                  featureA |       |
                     |     |       |
                  PR x---->|       |
                           |       |
release v2.0.1 - - - - - - | - - - + 2.0.2-SNAPSHOT
                           |       |
                           |       |     v2.1.x
release v2.1.0 - - - - - - + - - - X - - - + 2.1.1-SNAPSHOT
                           |               |
                           |               |
                  featureB |               |
                     |     |               |
                  PR x---->|               |
                          ...             ...

Versioning

We follow the Semantic Versioning scheme.

Backward compatibility

We distinguish between 3 kinds of (backward-)compatibilty:

  1. Source - Source compatibility concerns translating Java source code into class files.
  2. Binary - Binary compatibility is defined in The Java Language Specification as preserving the ability to link without error.
  3. Behavioral - Behavioral compatibility includes the semantics of the code that is executed at runtime.

Source: OpenJDK Developers Guide v0.777, Kinds of Compatibility

Given a version number <major>.<minor>.<path>, Vavr

  • may affect behavioral compatibility in all kind of releases, especially bug fix/patch releases. For example we might decide to release a more effective hashing algorithm in the next minor release that reduces the probability of collisions.
  • may affect source compatibility in patch releases. For example this may be the case when generic type bounds of method signatures need to be fixed.
  • retains binary backwards compatibility (drop in replacement jar) within the same minor version (this includes patch versions)
  • is not binary backward compatible when the major version changes

Summing up, drop-in replacements of Vavr can be made for minor and patch releases.

Major release

Performing a release

Performing a release requires admin-rights.

  1. get a fresh copy of the repo git clone https://github.com/vavr-io/vavr.git
  2. run ./gradlew clean check to ensure all is working fine
  3. perform the release ./gradlew release --info
  4. Go to http://oss.sonatype.org and stage the release.

Post-Release steps (e.g. for release v2.1.0)

  1. [CAUTION] Delete the old maintenance branch (e.g. v2.0.x)

    git push origin :v2.0.x

  2. Create the new maintenance branch (e.g. v2.1.x) based on the new release tag (e.g. v2.1.0)

    git checkout origin/master
git fetch origin
git branch v2.1.x v2.1.0
git checkout v2.1.x
git push origin v2.1.x

  3. Update the version of the maintenance branch in gradle.properties (e.g. 2.1.1-SNAPSHOT)

When a maintenance release is performed, we increase the last digit of the new development version of the maintenance branch (e.g. 2.1.2-SNAPSHOT).

Merging specific commits into the maintenance branch

Pull requests are merged into master. Only specific commits are merged from master into the maintenance branch.

git checkout v2.1.x
git log --date-order --date=iso --graph --full-history --all --pretty=format:'%x08%x09%C(red)%h %C(cyan)%ad%x08%x08%x08%x08%x08%x08%x08%x08%x08%x08%x08%x08%x08%x08%x08 %C(bold green)%aN%C(reset)%C(bold yellow)%d %C(reset)%s'
# pick one or more commits from the log, e.g. a741cf1.
git cherry-pick a741cf1

Bugfix release

Steps to bugfix and perform a release

Given a release 1.2.2, we create a bugfix release as follows.

First, we clone the repository. We work on origin instead of a fork (this requires admin rights).

git clone https://github.com/vavr-io/vavr.git vavr-1.2.3

We checkout the release tag and create a new (local) branch.

git checkout v1.2.2
git checkout -b bugfix-release-1.2.3

Then we create the new snapshot version by editing gradle.properties (e.g. 1.2.3-SNAPSHOT). Now the changes can be performed to the repository. After that, we test the changes.

./gradlew clean check

Then the new files can be added and the changes can be committed.

git add <files>
git commit -a -m "fixes #<issue>"

Then we perform the release as usual:

./gradlew release --info

Go to https://oss.sonatype.org and release to Maven Central.

Housekeeping

Delete the branch which was pushed by the maven release plugin to origin:

git checkout master
git branch -D bugfix-release-1.2.3
git push origin :bugfix-release-1.2.3

Release notes

For major, minor and bugfix releases we create release notes on Github.

Useful commands

The number of lines changed by author since a specific date:

git ls-files -z | xargs -0n1 git blame -w --since="3/18/2016" --line-porcelain | grep -a "^author " | sort -f | uniq -c | sort -n -r