EDITORIAL: accessing the "latest" versions of SAML documents

["Eve L. Maler" <Eve.Maler@Sun.COM>]

As agreed at this week's editorial team meeting, we're going to
start making the SAML specs and auxiliary documents available in
a new way from Kavi.

(Work item owners and other use case/solution proposal writers:
Note that this does not concern you!  You can keep doing whatever
it is you're doing regarding filenames and uploading to Kavi.
However, if you feel like adopting the mechanism detailed below,
go for it.)

For auxiliary documents such as the scope/work items document and
the issues list, I will be moving to a "revision-less" style,
where filenames will be denuded of their rev numbers.  Example:
sstc-saml-2.0-issues.pdf.  These documents contain all the
history and context any reader would need, so there's no need to
go back to a previous rev.  Kavi will be the only thing keeping
track of the old revs.

For specifications, the editors have agreed to upload both
revision-ful *and* identical revision-less forms for each new rev
of a spec, and to provide a bit more information on the title
page of each rev to point people to the previous rev for their
convenience.  See below for my proposal for how this additional
info should look.

The benefit is that the revision-less forms will get persistent
download IDs in the Kavi system, and thus persistent URLs.  Once
this process is complete, people will be able to bookmark the
"latest" versions of any of our documents, and we'll have an
easier time keeping the handcrafted links on the SAML public and
member home pages up to date.  However, for (say) implementors
who want to point to the specific rev that they conform to, or
people who need to cite a specific line number in reporting a
comment, a revision-full form will still be referenceable by URI.

Read on only if you're an editor or you have a morbid interest in
publication stuff...  Feel free to send comments or questions.

			*		*		*


The procedure for uploading new revs of existing documents is:

1. Go to the member-only TC documents page and find the document
you want to modify:
http://www.oasis-open.org/apps/org/workgroup/security/documents.php

2. Click on either the Details or the Manage link associated with
that document.  (Depending on how you got there and your
permissions, I'm not sure which you'll see.)

3. Click on the Add a Revision link.

4. Fill in the form.  It appears that in order to create a new
revision of an existing Kavi document that has a rev-less
filename, you can upload a file whose name on the client side is
different (viz., a filename with a rev number in it!).  This is a
good thing and eases the process on your (client) side.

5. If you're a spec editor and you've forgotten to upload the
rev-ful form the usual way, do that now.  For real SAML specs, we
need *both* rev-less and rev-ful versions in Kavi so that every
distinct draft is uniquely addressable by the world.

			*		*		*


For documents that are entirely revision-less, such as the issues
list, use this pattern on the title page (with the "Title page
info" and "Title page info description" style pair):

Document identifier:
   sstc-saml-2.0-issues

Publication date:
   5 February 2004

Location:
http://www.oasis-open.org/committees/download.php/5xxx/sstc-saml-2.0-issues-diff.pdf
http://www.oasis-open.org/committees/download.php/5271/sstc-saml-2.0-issues.pdf
http://www.oasis-open.org/committees/download.php/5270/sstc-saml-2.0-issues.sxw

Make sure to update the publication date in the footer and to
provide a fresh entry in the revision history.

			*		*		*


For documents that have both rev-less and rev-ful forms, such as
the core spec, use this pattern:

Document identifier:
   sstc-saml-core-2.0-draft-05

Location:
http://www.oasis-open.org/committees/documents.php?wg_abbrev=security

Location of latest revision:
http://www.oasis-open.org/committees/download.php/5xxx/sstc-saml-core-2.0-diff.pdf
http://www.oasis-open.org/committees/download.php/5xxx/sstc-saml-core-2.0.pdf
http://www.oasis-open.org/committees/download.php/5xxx/sstc-saml-core-2.0.sxw

Location of previous revision:
http://www.oasis-open.org/committees/download.php/5272/sstc-saml-core-2.0-draft-04-diff.pdf
http://www.oasis-open.org/committees/download.php/5271/sstc-saml-core-2.0-draft-04.pdf
http://www.oasis-open.org/committees/download.php/5270/sstc-saml-core-2.0-draft-04.sxw

Make sure to update the publication date and revision number in
the footer and to provide a fresh entry in the revision history.

			*		*		*


Note that either you'll have to "seed" a rev-less document on
Kavi with an old rev or an empty document in order to determine
the download ID, or you'll have to put a placeholder on your
title page until the download ID gets assigned and fill it in
when you upload some later rev.

	Eve
-- 
Eve Maler                                        +1 781 442 3190
Sun Microsystems                            cell +1 781 354 9441
Web Products, Technologies, and Standards    eve.maler @ sun.com