Common Build Version Specifier
Version 0.2
Overview
This proposal extends the URI Syntax proposal: /URISyntax
The key aims of this proposal are to:
formalise version-specifier for projects which provide formal and interim builds;
provide a set of best practices for such projects; and
enable tools to construct a URI to unambigously locate a particular project version using a set of known criteria
URI Components
An absolute repository URI is written as follows:
repository-uri = access-specifier "/" product-specifier "/"
version-specifier "/" artifact-specifier
This proposal defines version-specifier as follows:
version-specifier = build-version-specifier
build-version-specifier = formal-build | interim-build
formal-build = [formal-build-designation "/"] version
interim-build = interim-build-designation "/" version
[ "/" interim-version ]
interim-version = timestamp | latest
formal-build-designation = "release" | ...
interim-build-designation = "interim" | "nightly" | "snapshot" | ...
version = version-name | latest
version-name = pchar+ & ~(formal-build-designation | interim-build-designation | latest)
timestamp = YYYYMMDD ["." HHMM["SS"]]
latest = "latest"
(pchar is per http://www.ietf.org/rfc/rfc2396.txt)
Build
Builds are separated into formal and interim builds.
A formal build may be a final or milestone release. e.g:
"1.0", "release/1.0", "1.0-beta1", "release/1.0-rc1"
An interim build is an informal release, produced by
a nightly build or an ad-hoc snapshot. e.g:
"nightly/1.0/20031113", "snapshot/1.2beta1".
Version
Version is either "latest" or arbitrary, determined by the project or deployment tool. "latest" always refers to the latest version of a particular build, and may be supported using symbolic links, or via http redirection.
E.g:
http://repo.apache.org/apache/commons-cli/release/l.0/...
http://repo.apache.org/apache/commons-cli/release/l.1/...
http://repo.apache.org/apache/commons-cli/release/latest/...
-> symlink to ../1.1
Interim version
The interim version is either a timestamp, or "latest". The timestamp indicates the time of the build. "latest" always refers to the latest interim version and may be supported using symbolic links, or via http redirection.
E.g:
http://repo.apache.org/apache/commons-cli/nightly/1.0/20031112/...
http://repo.apache.org/apache/commons-cli/nightly/1.0/20031113/...
http://repo.apache.org/apache/commons-cli/nightly/1.0/latest/...
-> symlink to ../20031113
Rationale
Optional build designation for formal builds
<formal-build> is defined as:
formal-build = [formal-build-designation "/"] version formal-build-designation = "release" | ...
The formal-build-designation is optional for those projects which don't produce interim builds, or don't wish to add another directory for formal releases. E.g:
http://repo.apache.org/apache/commons-cli/l.0/... http://repo.apache.org/apache/commons-cli/l.1/...
Mandatory version in interim builds
<interim-build> is defined as:
interim-build = interim-build-designation "/" version
[ "/" interim-version ]
interim-version = timestamp | latest
This enables support for multiple versions of builds, if there are two or more concurrent development streams.
E.g, to support nightly builds of versions 1.0 and 2.0 of commons-cli:
http://repo.apache.org/apache/commons-cli/nightly/1.0/20031112/...
http://repo.apache.org/apache/commons-cli/nightly/1.0/20031113/...
http://repo.apache.org/apache/commons-cli/nightly/1.0/latest/...
-> symlink to ../20031113
http://repo.apache.org/apache/commons-cli/nightly/2.0/20031112/...
http://repo.apache.org/apache/commons-cli/nightly/2.0/20031113/...
http://repo.apache.org/apache/commons-cli/nightly/2.0/latest/...
-> symlink to ../20031113
Build designation naming conventions
<formal-build-designation> and <interim-build-designation> are defined as:
formal-build-designation = "release" | ... interim-build-designation = "interim" | "nightly" | "snapshot" | ...
In other words, tools may use "release", "interim" etc, but may also extend them to define their own.
Note: tools which parse repository URIs may not be able to handle custom build designation names.
Tool support
Tools can unambigously locate a project version given the following criteria:
formal or interim build-designation
Optional. If not specified, assume formal build.
version
Mandatory.
interim-version
Optional. If specified, build designation must also be specified.
Example 1
Given:
organisation = "apache" project = "commons-cli" version = "1.0" build-designation = interim-version =
The URI would be: http://repo.apache.org/apache/commons-cli/1.0
Example 2
Given:
organisation = "apache" project = "commons-cli" version = "latest" build-designation = interim-version =
The URI would be: http://repo.apache.org/apache/commons-cli/latest
If two versions of commons-cli are available, "1.0" and "1.1", the URI would resolve to: http://repo.apache.org/apache/commons-cli/1.1
Example 3
Given:
organisation = "apache" project = "commons-cli" version = "1.1" build-designation = "snapshot" interim-version = 20031113
The URI would be: http://repo.apache.org/apache/commons-cli/snapshot/1.1/20031113
Example 4
Given:
organisation = "apache" project = "commons-cli" version = "1.1" build-designation = "snapshot" interim-version = "latest"
The URI would be: http://repo.apache.org/apache/commons-cli/snapshot/1.1/latest
If two snapshot builds of commons-cli 1.1 are available, "20031112" and "20031113", the URI would resolve to: http://repo.apache.org/apache/commons-cli/snapshot/1.1/20031113
Example 5
Given:
organisation = "apache" project = "commons-cli" version = "latest" build-designation = "snapshot" interim-version = "latest"
The URI would be: http://repo.apache.org/apache/commons-cli/snapshot/latest/latest
If two versions or commons-cli are available, "1.0" and "1.1", and two snapshot builds of commons-cli 1.1 are available, "20031112" and "20031113", the URI would resolve to: http://repo.apache.org/apache/commons-cli/snapshot/1.1/20031113
Appendix
Changes from 0.1
Changed version-name from:
version-name = pchar+ to version-name = pchar+ & ~(formal-build-designation | interim-build-designation | latest)
Renamed build to build-version-specifier