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


Reply via email to