Re: General Comment on the Requirements Spec

At 2:35 +0100 12-02-1997, Yaron Goland wrote:
>The requirements MUST NOT tell the implementation authors how to do
>their job. This requirement spec oversteps its bounds when it moves away
>from stating goals to dictating implementation, as it does in section
>4.9.2.*. If the authors of the requirements spec do not like the current
>implementation they are free to comment on the mailing list. They should
>not, however, use the requirements document as a backdoor to put in
>their preferred implementations.

Defining the boundaries between requirement and solutions is not always
easy and univocal, and surely depends on the abstraction that is needed in
each case. We probably need a more abstract set of requirements, that do
not hint not only to the preferred solution, but even to the protocol that
needs to be addressed for the solution.

I propose thus that we remove any mention of URLs and HTTP, and just refer
to a more anodine and agreable "relevant standards", letting implementers
decide on what to change.

At the end of this mail I propose a different draft for section 4.9.2,
where implementation hints are further removed from the text.

Fabio

P.S. You hint that the current implementation was ignored when drafting the
requirements. On the contrary, these requirements are a more or less
literal merge of two previous documents, that were written and circulated
BEFORE the current implementation. That the requirements and the
implementation did not match we were able to notice: an agenda item was
proposed to reconcile them. But I wouldn't attribute automatically the
implementation any birthright, or the requirements' drafters any sneaky
attitude.

-----

4.9. Versioning

In the following discussion, "versioned resource" means a resource that
has the structure of a directed acyclic graph, each node of which is
a version. "Version" means a node in this structure, which is itself
a resource. Each version typically stands in a "derived from"
relationship to its predecessor(s).

4.9.1. General Principles

4.9.1.1. Stableness of versions. Most versioning systems are intended to
provide an accurate record of the history of evolution of a document.
This accuracy is ensured by the fact that a version eventually becomes
"frozen" and immutable. Once a version is frozen, further changes will
create new versions rather than modifying the original. In order for
caching and persistent references to be properly maintained, a client
must be able to determine that a version has been frozen. Any successful
attempt to retrieve a frozen version of a resource will always retrieve
exactly the same content, or return an error if that version (or the
resource itself) are no longer available.
[Removed mentions of URLs and HTTP Entity tags. Removed freezing behaviour
for locked and unlocked resources]

4.9.1.2. Policy-free Versioning. Haake and Hicks [5] have identified
the notion of versioning styles (referred to here as versioning
policies, to reflect the nature of client/server interaction) as one
way to think about the different policies that versioning systems
implement. Versioning policies include decisions on the shape of
version histories (linear or branched), the granularity of change
tracking, locking requirements made by a server, etc. The protocol
should clearly identify the policies that it dictates and the
policies that are left variable for the implementations, and
work towards inter-operability across servers and clients with regards
to the latter ones.
[The policy-free requirements were mitigated]

4.9.1.3. Separation of resource retrieval and concurrency control. The
protocol must separate the reservation and release of versioned
resources from their access methods. Provided that consistency
constraints are met before, during and after the modification of a
versioned resource, no single policy for accessing a resource should be
enforced by the protocol. For instance, a user may declare an intention
to write before or after retrieving a resource via GET, may PUT a
resource without releasing the lock, and might even request a lock via
HTTP, but then retrieve the document using another communication
channel such as FTP.

[Not changed. It looks reasonable, not implementation-oriented,
and fully justifiable to me.]

4.9.1.4 Parsimony in client-server interactions. Versioning a resource
implies that a potentially large quantity of important information about a
resource that is known to the server providing it is unknown to the client
receiving it. The protocol must make sure that the amount of interactions
between the client and the server in order for the client to obtain this
information is kept to a logical minimum, preventing unneeded or avoidable
further requests.

[New]

4.9.2. Functional Requirements

4.9.2.1. Referring to a versioned resource. There should be a way to
refer to a versioned resource as a whole.
Some queries about the versioning status of a resource do not apply
only to one version of that resource, but to the resource as a whole.
Furthermore some operations may affect all versions of a resource,
rather than any specific version. In these cases a way to refer to the
whole version is required.

4.9.2.2. Referring to specific versions. There should be a way to refer
to each individual versions of a versioned resource.
This means that a version is itself a resource. This is required for
version-specific linking, and for non-versioning client support.

[4.9.2.1 and 4.9.2.2 were inverted. Mentions of URLs removed.]

4.9.2.3. A way for the client to determine whether a resource is versioned,
or whether a resource is itself a version of another resource.

The protocol should provide a way for the client to be able to determine
important versioning facts about a resource.

[Was 4.9.2.6. Mentions of URLs removed. Added further restriction on the
identification of a versioned resource]

4.9.2.4. Referring to a server-defined "default", "current" or "tip"
version of a resource.

The protocol must guarantee that a significant result, in the form of a
default version of the resource, is returned for requests from
non-versioning clients and requests where no special version information is
provided.
This does not rule out the possibility of a server returning an error when
no sensible default exists.

[Was 4.9.2.3. Removed implementation hints and justifications]

4.9.2.5. It should be possible for the clients to determine the following
interesting facts about a resource *without having the resource itself*:
whether it is a versioned resource, how to get the default version, how to
get the whole resource if it is a version of a versioned resource.

Being able to determine these facts of a versioned resource makes it
possible to implement browsing the version tree and deducing facts about it
without necessarily getting the relevant resources. This also supports some
comparison operations: It makes it possible to
determine whether two references designate versions of the same versioned
resource.

[Was 4.9.2.7. Trasformed so as to specify the functionality required,
rather than the way to get it.]

4.9.2.6. It should be possible for the clients to determine and access the
following related resources of a version of a resource:
   o root version(s) of this version
   o predecessor version(s) of this version
   o successor version(s) of this version
   o default version of this version [also in 4.9.2.4. Redundant?]
It must be possible in some way for a versioning client to access
versions related to a resource currently being exhamined. It is not
strictly necessary that these operations are avaiable without having the
resource first.

[Was 4.9.2.4. Removed mentions to URLs]

4.9.2.7. A way to retrieve the complete version topology for a resource.
There should be a way to retrieve information about all versions of a
resource. The format for this information must be standardized so that
the basic information can be used by all clients. Other specialized
formats should be accomodated, for servers and clients that require
information that cannot be included in the standard topology.

[Was 4.9.2.5. Untouched]

[4.9.2.8. (Lock). Removed as handled in section 4.3 "Locking" already.]

[4.9.2.9. (Unlock). Removed as handled in section 4.3 "Locking" already.]

[4.9.2.10. (Reserve). Removed as handled in section 4.4 "Notification of
Intent to Edit". I prefer the word "Reserve", though]

[4.9.2.11. (Release). Removed since I feel overlaps with proposed
"Uncheckout", to be put somewhere else (for instance, section 4.4
"Notification of Intent to Edit"). I prefer the word "Release", though.]

4.9.2.12. A way to submit a new version of a resource (PUT). The server
should be able to attach it to the correct part of the version tree,
based on the version number associated with the resource before its
modification.

[Unchanged. Possibly this is not the best place to put it. How about
generalizing section 4.6 "Partial Write", and have it become "Write"
(including partial and total)?]

4.9.2.13. A way for a client to request a version identifier for a
checked out version. Such an identifier will not be used by any other
client in the meantime. The server may refuse the request.

[Unchanged]

4.9.2.14. A way for a client to propose a version identifier upon
submitting a version of a resource. The server may refuse to to use
the client's suggested version identifier.

[Unchanged]


[4.9.2.15. (Metadata). Removed as handled in section 4.1 "Attributes" already.]

[4.9.2.16. (A way for a server to provide a version identifier to be used
for a resource in further operations). Removed since it is strictly an
implementation decision. The fuctionality it was needed for is contained in
the following 4.9.2.17]

4.9.2.17. A way for a client to query the server for information about a
version tree, including which versions are locked, which are reserved for
editing, and by whom (Session Tracking).

[Changed to reflect implementation-independence.]

4.9.3. Rationale

[Unchanged]

Versioning in the context of the world-wide web offers a variety of
benefits:

It provides infrastructure for efficient and controlled management of
large evolving web sites. Modern configuration management systems are
built on some form of repository that can track the revision history of
individual resources, and provide the higher-level tools to manage
those saved versions. Basic versioning capabilities are required to
support such systems.

It allows parallel development and update of single resources. Since
versioning systems register change by creating new objects, they
enable simultaneous write access by allowing the creation of variant
versions. Many also provide merge support to ease the reverse operation.

It provides a framework for access control over resources. While
specifics vary, most systems provide some method of controlling or
tracking access to enable collaborative resource development.

It allows browsing through past and alternative versions of a resource.
Frequently the modification and authorship history of a resource is
critical information in itself.

It provides stable names that can support externally stored links for
annotation and link-server support. Both annotation and link servers
frequently need to store stable references to portions of resources
that are not under their direct control. By providing stable states of
resources, version control systems allow not only stable pointers into
those resources, but also well-defined methods to determine the
relationships of those states of a resource.

It allows explicit semantic representation of single resources with
multiple states. A versioning system directly represents the fact that
a resource has an explicit history, and a persistent identity across
the various states it has had during the course of that history.

Received on Friday, 14 February 1997 05:58:38 UTC