dorkbox/Version
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Update README for version 0.6.0

Browse Source
This commit is contained in:
Zafar Khaja 2013-03-31 14:20:22 +04:00
parent 670b1a77c1
commit fc344ba562
1 changed files with 112 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

147
README.md
View File

@ -1,19 +1,19 @@
Java SemVer v0.5.0 [![Build Status](https://travis-ci.org/zafarkhaja/java-semver.png)](https://travis-ci.org/zafarkhaja/java-semver) Java SemVer v0.6.0 [![Build Status](https://travis-ci.org/zafarkhaja/java-semver.png)](https://travis-ci.org/zafarkhaja/java-semver)
================== ==================
Java SemVer is a Java implementation of the Semantic Versioning Specification Java SemVer is a Java implementation of the Semantic Versioning Specification
(http://semver.org/). (http://semver.org/).
**NOTE**: The current version of the Java SemVer corresponds to the Semantic **NOTE**: The current version of the Java SemVer corresponds to the Semantic
Versioning 2.0.0-rc.1. Versioning 2.0.0-rc.2.
Versioning Versioning
---------- ----------
Java SemVer is versioned according to the SemVer Specification. Java SemVer is versioned according to the SemVer Specification.
**NOTE**: The current release of the Java SemVer library has a major version of **NOTE**: The current release of the Java SemVer library has a major version of
zero which according to the SemVer p.4 means that the library is under initial zero which according to the SemVer p.4 means that the library is under initial
development and its public API should not be considered stable. development and its public API should not be considered stable.
@ -22,12 +22,12 @@ Usage
Below are some common use cases for the Java SemVer library. Below are some common use cases for the Java SemVer library.
### Creating Versions ### ### Creating Versions ###
Java SemVer library is composed of one small package which contains a few Java SemVer library is composed of one small package which contains a few
classes. All the classes but one are package-private and are not accessible classes. All the classes but one are package-private and are not accessible
outside the package. The only public class is `Version` which acts as a outside the package. The only public class is `Version` which acts as a
_facade_ for the client code. By design, the `Version` class is made immutable _facade_ for the client code. By design, the `Version` class is made immutable
by making its constructor package-private, so that it can not be subclassed or by making its constructor package-private, so that it can not be subclassed or
directly instantiated. Instead of public constructor, the `Version` class directly instantiated. Instead of public constructor, the `Version` class
provides a _static factory method_, `Version.valueOf(String value)`. provides a _static factory method_, `Version.valueOf(String value)`.
```java ```java
@ -41,35 +41,103 @@ int patch = v.getPatchVersion(); // 0
String normal = v.getNormalVersion(); // "1.0.0" String normal = v.getNormalVersion(); // "1.0.0"
String preRelease = v.getPreReleaseVersion(); // "rc.1" String preRelease = v.getPreReleaseVersion(); // "rc.1"
String build = v.getBuildVersion(); // "build.1" String build = v.getBuildMetadata(); // "build.1"
String str = v.toString(); // "1.0.0-rc.1+build.1"
```
Another way to create a `Version` is to use a _builder_ class `Version.Builder`.
```java
import com.github.zafarkhaja.semver.Version;
Version.Builder builder = new Version.Builder("1.0.0");
builder.setPreReleaseVersion("rc.1");
builder.setBuildMetadata("build.1");
Version v = builder.build();
int major = v.getMajorVersion(); // 1
int minor = v.getMinorVersion(); // 0
int patch = v.getPatchVersion(); // 0
String normal = v.getNormalVersion(); // "1.0.0"
String preRelease = v.getPreReleaseVersion(); // "rc.1"
String build = v.getBuildMetadata(); // "build.1"
String str = v.toString(); // "1.0.0-rc.1+build.1" String str = v.toString(); // "1.0.0-rc.1+build.1"
``` ```
### Incrementing Versions ### ### Incrementing Versions ###
Because the `Version` class is immutable, the _incrementors_ return a new Because the `Version` class is immutable, the _incrementors_ return a new
instance of `Version` rather than modifying the given one. instance of `Version` rather than modifying the given one. Each of the normal
version incrementors has an overloaded method that takes a pre-release version
as an argument.
```java ```java
import com.github.zafarkhaja.semver.Version; import com.github.zafarkhaja.semver.Version;
Version v1 = Version.valueOf("1.2.3"); Version v1 = Version.valueOf("1.2.3");
Version v2 = v1.incrementMajorVersion(); // Incrementing major version
String str = v2.toString(); // "2.0.0" Version v2 = v1.incrementMajorVersion(); // "2.0.0"
Version v2 = v1.incrementMajorVersion("alpha"); // "2.0.0-alpha"
Version v3 = v1.incrementMinorVersion(); // Incrementing minor version
String str = v3.toString(); // "1.3.0" Version v3 = v1.incrementMinorVersion(); // "1.3.0"
Version v3 = v1.incrementMinorVersion("alpha"); // "1.3.0-alpha"
Version v4 = v1.incrementPatchVersion(); // Incrementing patch version
String str = v4.toString(); // "1.2.4" Version v4 = v1.incrementPatchVersion(); // "1.2.4"
Version v4 = v1.incrementPatchVersion("alpha"); // "1.2.4-alpha"
// Original Version is still the same
String str = v1.toString(); // "1.2.3" String str = v1.toString(); // "1.2.3"
``` ```
There are also incrementor methods for pre-release version and build metadata.
```java
import com.github.zafarkhaja.semver.Version;
// Incrementing pre-release version
Version v1 = Version.valueOf("1.2.3-rc"); // considered as "rc.0"
Version v2 = v1.incrementPreReleaseVersion(); // "1.2.3-rc.1"
Version v3 = v2.incrementPreReleaseVersion(); // "1.2.3-rc.2"
// Incrementing build metadata
Version v1 = Version.valueOf("1.2.3-rc+build"); // considered as "build.0"
Version v2 = v1.incrementBuildMetadata(); // "1.2.3-rc+build.1"
Version v3 = v2.incrementBuildMetadata(); // "1.2.3-rc+build.2"
```
When incrementing normal or pre-release versions build metadata is always dropped.
```java
import com.github.zafarkhaja.semver.Version;
Version v1 = Version.valueOf("1.2.3-beta+build");
// Incrementing normal version
Version v2 = v1.incrementMajorVersion(); // "2.0.0"
Version v2 = v1.incrementMajorVersion("alpha"); // "2.0.0-alpha"
Version v3 = v1.incrementMinorVersion(); // "1.3.0"
Version v3 = v1.incrementMinorVersion("alpha"); // "1.3.0-alpha"
Version v4 = v1.incrementPatchVersion(); // "1.2.4"
Version v4 = v1.incrementPatchVersion("alpha"); // "1.2.4-alpha"
// Incrementing pre-release version
Version v2 = v1.incrementPreReleaseVersion(); // "1.2.3-beta.1"
```
**NOTE**: The discussion page https://github.com/mojombo/semver/issues/60 might
be of good use in better understanding some of the decisions made regarding the
incrementor methods.
### Comparing Versions ### ### Comparing Versions ###
Comparing versions with Java SemVer is easy. The `Version` class implements the Comparing versions with Java SemVer is easy. The `Version` class implements the
`Comparable` interface, it also overrides the `Object.equals(Object obj)` method `Comparable` interface, it also overrides the `Object.equals(Object obj)` method
and provides some more methods for convenient comparing. and provides some more methods for convenient comparing.
```java ```java
@ -87,24 +155,33 @@ boolean result = v1.lessThan(v2); // true
boolean result = v1.lessThanOrEqualsTo(v2); // true boolean result = v1.lessThanOrEqualsTo(v2); // true
``` ```
When determining version precedence build metadata is ignored (SemVer p.10).
Issues
------
As of the moment, the Specification is not clear about what should be the
behavior of pre-release and build versions when the normal version numbers are
incremented. Below is an example of what I mean:
```java ```java
import com.github.zafarkhaja.semver.Version; import com.github.zafarkhaja.semver.Version;
Version v1 = Version.valueOf("1.2.3-alpha+build"); Version v1 = Version.valueOf("1.0.0+build.1");
Version v2 = v1.incrementMajorVersion(); Version v2 = Version.valueOf("1.0.0+build.2");
String normal = v2.getNormalVersion(); // "2.0.0" int result = v1.compareTo(v2); // = 0
String preRelease = v2.getPreReleaseVersion(); // "" OR "alpha" OR "alpha1" OR "alpha2" ? boolean result = v1.equals(v2); // true
String build = v2.getBuildVersion(); // "" OR "build" OR "build1" OR "build2" ? ```
Sometimes, however, you might want to compare versions with build metadata in
mind. For such cases Java SemVer provides a _comparator_ `Version.BUILD_AWARE_ORDER`
and a convenience method `Version.compareWithBuildsTo(Version other)`.
```java
import com.github.zafarkhaja.semver.Version;
Version v1 = Version.valueOf("1.0.0+build.1");
Version v2 = Version.valueOf("1.0.0+build.2");
int result = Version.BUILD_AWARE_ORDER.compare(v1, v2); // < 0
int result = v1.compareWithBuildsTo(v2); // < 0
boolean result = v1.equals(v2); // false
``` ```
Also, see the discussion page https://github.com/mojombo/semver/issues/60.
TODO TODO