Tim,

I *love* your specifications, I really appreciate the clear/concise/explicit
nature of them. I only wish you'd use Wiki not EyeBrowse as your persistent
documentation tool. Wiki has versioning (so we can see older copies should
we need to refer back) and such, and allows other to make (respectful)
changes, and allows a view not cluttered throughout mail threads.

I'm game to be your cut-n-paste-wallah if you really need one, but please
(at least) refer to your proposals in the Wiki.

regards

Adam
----- Original Message ----- 
From: "Tim Anderson" <[EMAIL PROTECTED]>
To: <[EMAIL PROTECTED]>
Sent: Friday, November 14, 2003 8:21 PM
Subject: [proposal] common build version specifier - v0.1


> 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