Section 2.1.1 comments

Section 2.1.1:

It took me a long time to figure out exactly what was being described here.
I think my confusion derived from not understanding that there were three
separate entities being discussed:

- version-controlled resource
- version resource
- version history

I think my confusion would be eased by changing the second, third, and
fourth sentences of the first paragraph of Section 2.1.1 to more clearly
identify the three resources, and the fact that the unversioned resource is
being converted into a new type of resource, the version-controlled
resource.

----------

VERSION-CONTROL, when invoked on a resource with URL U, performs three
distinct operations:

1) It creates a new "version resource" whose body and dead properties are a
copy of the original, unversioned resource. The server assigns this resource
a new URL, VR, which is different from the original URL U.
2) It converts the unversioned resource into a "version-controlled
resource". The version-controlled resource keeps the original URL U. As part
of this conversion, it adds the DAV:checked-in property, whose value is the
URL of the version resource created in step #1.
3) It creates a new "version history resource" whose state initially just
contains URL VR, since that is, at present, the only version in the version
history.

Thus, whereas before VERSION-CONTROL, there was only one, unversioned
resource, after VERSION-CONTROL there are three separate, distinct
resources, each containing their own state and properties: the
version-controlled resource, the version resource, and the version history
resource. In core versioning, a version history resource is not assigned a
URL, and hence is not visible in the http scheme URL space. However, when
the version-history option (Section 5) is supported, this changes, and the
version history resource does have a URL.

----------

With this change, the first sentence of the second paragraph is no longer
needed.

I recommend moving the third paragraph, and the figure following, to
immediately after the second paragraph. Plus, I recommend labeling all of
the boxes in the figure, as follows:


          ===VERSION-CONTROL==>

                    |                       +----+
                    |                       |    | version history
                    |                       +----+
                    |                         |
        /foo.html   |   /foo.html             |
                    |                         v
         +----+     |     +----+ checked-in +----+
         | S1 |     |     | S1 | ---------->| S1 | version resource
         +----+     |     +----+            +----+ URL: /hist/73/v1
      unversioned   | version-controlled
        resource    |     resource

Adding an arrowhead to the lines between the version-controlled resource and
the version resource, and the version history and the version resource,
would also be helpful, since this is fairly conventional for pointers.

In the third paragraph, the third sentence ("The new version resource is
identified...") should be changed to:

"The original unversioned resource is converted into a version-controlled
resource, whose DAV:checked-in property identifies the version resource."

Using "version-controlled resource" is more clear than using the elliptical
"resource that is now under version control." (The artist formerly known as
Prince... ;-)


In the second paragraph, I recommend changing the second sentence "When a
method is applied..." to:

Since the version-controlled resource and version resources are separate,
distinct resources, when a method is applied to the version-controlled
resource, it only applies to the version-controlled resource, and does not
apply to the version resource that is currently identified by the
DAV:checked-in property.

- Jim

Received on Wednesday, 31 January 2001 19:50:30 UTC