Fw: [new issue] Versioning and Extensibility cleanup with DIFF

as per the request for a diff of the text, sorry that i can't generate 
pdf, but I don't have acrobat software.

Maryann

----- Forwarded by Maryann Hondo/Austin/IBM on 03/29/2007 02:12 PM -----

Maryann Hondo/Austin/IBM 
03/23/2007 11:39 AM

To
public-ws-policy@w3.org
cc

Subject
[new issue] Versioning and Extensibility cleanup





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


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.