<sarcasm>
Gee, I wonder if a "Working Draft" is different from a "Draft Standard"
???????
Of course, I have trouble telling a "Surf Board" from a "School Board"
because they both have the word "Board" in them.
Maybe it's just me.
</sarcasm>
Perhaps if we skip the short cuts and called a working draft a working
draft (and not a draft) we wouldn't have this confusion.
**********************************************
Don Wright don@lexmark.com
Chair, IEEE SA Standards Board
Member, IEEE-ISTO Board of Directors
f.wright@ieee.org / f.wright@computer.org
Director, Alliances & Standards
Lexmark International
740 New Circle Rd
Lexington, Ky 40550
859-825-4808 (phone) 603-963-8352 (fax)
**********************************************
"McDonald, Ira" <imcdonald@sharplabs.com>@pwg.org on 02/04/2003 10:56:26 AM
Sent by: owner-ps@pwg.org
To: "'HALL,DAVID (HP-Vancouver,ex1)'" <dhall@hp.com>, "'ps@pwg.org'"
<ps@pwg.org>
cc:
Subject: RE: PS> PSI WebEx Info and Versioning Discussion Material
Hi Dave,
You've just shown an example of why I urged that we reduce
the PWG 'standards track' to two states last Thursday.
The IETF (and current PWG) 'standards track' states are:
(a) Proposed (b) Draft (c) Standard.
The overloading of 'draft' in both Working-Draft and the
MIDDLE state of the 'standards track' is a bad problem.
Also, the IETF actually VERY rarely advances a document
all the way to 'Standard'. Mostly, they struggle to
get to 'Draft Standard'.
Cheers,
- Ira McDonald
High North Inc
-----Original Message-----
From: HALL,DAVID (HP-Vancouver,ex1) [mailto:dhall@hp.com]
Sent: Tuesday, February 04, 2003 9:50 AM
To: 'ps@pwg.org'
Subject: PS> PSI WebEx Info and Versioning Discussion Material
-------------------------
MEETING SUMMARY
-------------------------
Name: psi
Date: 2/4/2003
Time: 8:00AM, (GMT -08:00) Pacific Time, USA & Canada
Meeting Number: 21865515
Meeting Password: newpsi
Things we need to track:
Specification Document Version - (IPP 1.0, IPP 1.1, PSI 1.0, PSI 1.1, etc)
Specification Document Revision - (Date?)
Specification Goodness - (3 states, with ability to differentiate a
document
that has just been published from one that has been accepted)
- States: (a) Draft, (b) Proposal, (c) Standard
- Acceptance: (1) Working, (2) Accepted
Individual Interface Version - (0.01 - 0.99, 1.0.0, 1.0.1, 1.0.2, 1.0.3,
1.1.0, 1.1.1, 1.1.2, etc)
Individual Interface Revision - (1, 2, 3, 4, 5...)
Individual Interface Namespace - (?)
Schema Revision - (0.01 - 0.99, 1.0.0, 1.0.1, 1.0.2, etc)
Schema Namespace - (?)
Requirements:
Published WSDL and Schema needs to remain accessible.
A Specification Document should be able to refer to different Interface
Revisions.
(i.e. 1.1 of the PSI Specification should be able to reference
QueryEndPointsInterface v1.0.5 if we don't need to change it for 1.1)
Reference:
<
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnservice/
html/service04032002.asp>
Versioning
Everyone who developed COM applications: How many of you remember the
golden
rules of versioning? Okay, hands down. As a quick review, here are the
rules:
1. Always increment the version number.
2. Freeze the interface on the previous version. All new features
should go into a new interface.
3. Freeze all structures used on the previous version. Any enhancements
to those structures should show up in new structures.
WSDL version indication is done via the targetNamespace attribute of the
definitions element. This namespace gives the SOAP messages meaning by
relating the messages to a specific bit of code implemented somewhere on
the
server. The targetNamespace attribute has an XSD type of anyURI. This
attribute could be used in a large number of ways to indicate the version.
For a service named Foo that was hosted at msdn.microsoft.com, a few
options
exist for the first version.
Option 1:
The targetNamespace could be named http://msdn.microsoft.com/foo. This
works
by giving the interface a unique namespace name. This option does not fit
our needs, however, because it does not include an obvious mechanism for
indicating whether one version is earlier or later than another. I suppose
you could follow up later versions of the interface with namespaces such as
http://msdn.microsoft.com/foo1 and http://msdn.microsoft.com/foo2, but that
seems silly.
Option 2:
The targetNamespace could be named http://msdn.microsoft.com/1.0/foo.
Again,
this gives the interface a unique namespace identifier. This option fits
our
needs, because it gives us an obvious indicator of version as well as a
place to increment that version in a way people are used to seeing. As we
are dealing with an XML-centric world, however, we might do well to follow
the lead of the newer XML specifications, such as SOAP 1.2, XML Schema, and
XSLT. While this option is viable, it does not follow this lead.
Option 3:
Call the targetNamespace http://msdn.microsoft.com/2002/04/foo. This has a
few small advantages over option 2. For one, this is the versioning scheme
employed by the newer XML specifications. People who are used to looking at
XML will find versioning by date more familiar. As an added bonus,
versioning by date allows a person or machine to easily figure out when the
version was released. You can increase the resolution of the version to
reflect the frequency of releases. A resolution down to the hour would
indicate that releases are coming out far too frequently. If your team does
nightly builds, extend the interim granularity of the version to the date
of
the build. Regardless of what you do, don't be cute and use zero-based
month
and day-of-month numbers. It's counterintuitive.
Of the above options, both 2 and 3 fit the bill, with 3 being the
versioning
option that many XML users I have talked to like the best. An added
advantage of date-based versioning is that you will know how long the
interface has been available.
When changing an XSD type, create a brand new type in a brand new
namespace.
This new namespace should still stick with your versioning model. If the
first version was in a namespace such as
http://foo.org/bar/2001/11/20/types, the new namespace should only change
the date information. That new type, if published on April 5, 2002, should
be in the namespace http://foo.org/bar/2002/04/05/types. Any related
sub-types should remain in the old namespace and simply get imported into
the new one. Here, no wishy-washy answers.
To sum things up, here are the guidelines to use when updating an
interface:
* The changes always go into a new namespace.
* The new interface should be a superset of the old one.
* It is a good idea to keep the data model the same when versioning
the interface.
* Never revise data structures. Instead, add new ones as needed.
This archive was generated by hypermail 2b29 : Tue Feb 04 2003 - 11:21:13 EST