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