[Bug 4414] Versioning and Extensibility cleanup in Primer

http://www.w3.org/Bugs/Public/show_bug.cgi?id=4414

           Summary: Versioning and Extensibility cleanup in Primer
           Product: WS-Policy
           Version: PR
          Platform: PC
        OS/Version: Windows XP
            Status: NEW
          Severity: normal
          Priority: P2
         Component: Primer
        AssignedTo: fsasaki@w3.org
        ReportedBy: mhondo@us.ibm.com
         QAContact: public-ws-policy-qa@w3.org


Title:  versioning and extensibility in primer needs cleanup

Description:  the language in the primer should be consistent in its use of
"policy" and "policy expression".  " Policy assertion" design and best practice
should be moved to the Guidelines document.

Justification: the guidelines is supposed to contain guidance on policy
assertion authoring and the primer on policy expression use ....but the text
mixes the two roles and is confusing.

Proposal:

Part 1-----------------------------------3.8 Extensibility and Versioning
(after example 3-12)
From:

In this versioning scenario, policy can be used to represent current and
advanced behaviors in a non-disruptive manner: no immediate changes to existing
clients are required and these clients can smoothly migrate to new
functionality when they choose to. This level of versioning support in policy
enables the same class of versioning best practices built into WSDL constructs
such as service, port and binding.

To:

In this versioning scenario, a policy expression with multiple alternatives can
be used to represent current and advanced behaviors in a non-disruptive manner:
no immediate changes to existing clients are required and these clients can
smoothly migrate to new functionality when they choose to. This level of
versioning support in a policy expression  enables the same class of versioning
best practices built into WSDL constructs such as service, port and binding.

Part 2 -------------------------------------------------------3.8.1 Ignorable
and Versioning
In this section, the expiry date and time are not a "domain expression" but a
new assertion. The last sentence  should be in the Guidelines document.

From:

3.8.1 Ignorable and Versioning
One potential use of the wsp:Ignorable attribute is to mark versioning related
information. One scenario is that a service will support a particular version
of a service until a certain point in time. After that time, the service will
not be supported. The expiry date and time of the service would be a domain
expression, but it could be marked as ignorable. When an alternative does have
an expiry, it is usually useful to convey this information to help smooth the
versioning process. 
....
In a scenario such as this, where an assertion type is used for ignorable
information, the use of strict or lax mode and presence or absence of the
assertion type in the first version are important decisions. If Company-X
wishes clients to always be able to ignore the assertion, particularly those
using strict intersection, the first policy alternative offered should contain
the policy assertion type. If Company-X adds the policy assertion type to a
subsequent alternative, then requesters using strict mode will not understand
the assertion type and the alternative with the ignorable information will not
be compatible with the older version of the alternative as per the intersection
rules. Thus the widest possible alternative compatibility will be to have the
ignorable policy assertion type in the very first version of the alternative.
The second alternative shown also contains the hypothetical EndOfLife policy
Assertion type. Because the actual value is not known, a value that is roughly
infinitely in the future is used. A subsequent policy alternative could refine
the value. 


To:


3.8.1 Ignorable and Versioning
One potential use of the wsp:Ignorable attribute is to mark versioning related
information. One scenario is that a service will support a particular version
of a service until a certain point in time. After that time, the service will
not be supported. The expiry date and time of the service would be a new policy
assertion[see Guidelines document for best practices on defining new policy
assertions and the use of the ignorable attribute] , with an ignorable
attribute. 
....
In a scenario such as this, Company-X is acting as both an assertion author and
a policy expression author.

As a policy expression author, when an assertion type is used for ignorable
information, the use of strict or lax mode and presence or absence of the
assertion type in the first version are important decisions.  

<sidebar--- this is another case where "best practices" are evident in the
primer as opposed to the guidelines. Also, I'm not sure whether we agree as a
group that it is a "best practice" to add a fictitious assertion to every
policy alternative to anticipate a future need. I believe the text below is
also a valid way to address intersection and compatability. >

<alternative to current text>
If Company-X wishes clients to always be able to use the original policy
expression,  particularly those using strict intersection, the first policy
alternative offered should NOT contain the EndOfLife policy assertion type. 
If Company-X adds the EndOfLife policy  assertion type to a subsequent
alternative, then requesters using strict mode will not understand the
EndOfLife policy assertion type and the new alternative with the ignorable
information will not be compatible with the older version of the alternative as
per the intersection rules. Thus to provide the widest possible alternative
compatibility Company-X should NOT have the ignorable attribute on the
EndOfLife policy assertion in the very first alternative. The second
alternative  contains the EndOfLife policy Assertion type with an ignorable
attribute.

Received on Friday, 23 March 2007 15:38:29 UTC