Overview
========
This proposal extends the URI Syntax proposal, v0.2:
http://nagoya.apache.org/eyebrowse/[EMAIL PROTECTED]&ms
gNo=367
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
build = formal-build | interim-build
formal-build = [formal-build-designation "/"] version
interim-build = interim-build-designation "/" version
[ "/" interim-version ]
interim-version = "latest" | YYYYMMDD ["-" HHMM [SS]]
formal-build-designation = "release" | ...
interim-build-designation = "interim" | "nightly" | "snapshot" | ...
version = "latest" | *pchar
(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".
"latest" always refers to the latest interim version and
may be supported using symbolic links, or via http
redirection.
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 = "latest" | YYYYMMDD ["-" HHMM [SS]]
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.
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
