OK. As far as how
often to give new wd’s to the WG I think weekly is too often. I would suggest
monthly or at the request of the chair’s. People are not going to reread the
spec, or even just search and review change bars on a weekly basis. Monthly or
after a major revision seems like the doc would get more review. I don’t care
too much about this point though. I’ll review it anyway.
I would note that if
new wds do come out this often you may need to provide diffs not just from the
last wd but from the cd (or the wd of the cd after reordering…). The reason is
that many people would read every other one or even less frequently so would
not recognize change bars from only the last wd.
From:
Yalcinalp, Umit [mailto:umit.yalcinalp@sap.com]
Sent: Friday, October 28, 2005 9:41
AM
To: Marc Goodner; Gilbert
Pilz; ws-rx-editors@lists.oasis-open.org
Subject: RE: [ws-rx-editors] Document
titles and revision management
Not really. I am not
sure I explained my point well. Lets me also address your concerns.
The method I am
describing DOES NOT require the tc to see many conflicting revision numbers 01
followed by 23.
Here is the trick.
Lets take a doc revision wsrmp-1.1-spec-wd-01.
Editors
wsrmp-1.1-spec-wd-01 will many revisions of this document, none of them will
be marked with a separate number with naming, but its internal revision (hence
wsrmp-1.1-spec-wd-01 (01), wsrmp-1.1-spec-wd-01 (02), ... wsrmp-1.1-spec-wd-01
(0n). They constitue the changes that editors only make to this document.
When we decide to
publish the last document to the tc this document becomes the version in the
tc's list:
wsrmp-1.1-spec-wd-01
(0n) ==> wsrmp-1.1-spec-wd-01. Since the (0n) version is the last revision,
it becomes the TC's version.
The editors now
create wsrmp-1.1-spec-wd-02 in the editors tree and start applying incremental
changes to it until it gets published to the TC hence wsrmp-1.1-spec-wd-02
(0m) ==> wsrmp-1.1-spec-wd-02 in the TC document workspace.
So far, the TC is
seeing only the result of the increments.
When the document
becomes CD/whatever
wsrmp-1.1-spec-wd-XX
=> wsrmp-1.1-spec-cd-XX.
Hope this makes
sense.
We can reflect the XX
to match the public view of the revision if you want to make it simpler for
external folks to review the document numbers.
This is actually no
more work. It helps editors to do their incremental changes, so we can freely
work on a branch until the branch gets "published" to the tc. The diffs are
between previous numbers anyway. I actually found Kavi to be helpful in this
regard since I can manage the revisions and when I publish to the tc. I take
the last version and move it to the tc's publication point. It is darn simple
to maintain. I also updated the description of the document to contain all the
changes that have been applied to the document so it reflects all the changes
from the last non-incremental version. This information is what the TC, esp.
Paul cares about.
You should also not
have a concern about the revisions. The OpenOffice diff facility is really
handy about this. You can get a diff between two arbitrary documents. (Thanks
to Anish who educated me about this one!) Once a version is published to the
TC, it is very easy to generate a diff between the version that is in the TC's
document repository and the previous version. Hence, ALL the changes that went
into the TC published version (meaning incremental changes) are visible.
In this manner, the
TC is not confused as to why they are getting many "versions". We publish the
version when we like to them, announce it and they have it. If they want to
see all the versions of a particular version, they can look at the Editor's
repository. Nothing is lost, but clutter is avoided.
The question is how
often to send a version to the tc as a wd. We can do this weekly.
--umit
Ps. I would not want
to devise a semi CVS, but at least this system I believe will work to help
both the editors and the tc.
From: Marc
Goodner [mailto:mgoodner@microsoft.com]
Sent: Thursday, Oct 27, 2005 9:47
PM
To: Gilbert Pilz;
ws-rx-editors@lists.oasis-open.org
Subject: RE: [ws-rx-editors] Document
titles and revision management
OK, now I
understand.
The method as
described has many revisions over a wd until piping up to the TC that it’s
ready for review. At that point no more revisions would be made against that
wd and if any editorial or other changes were needed it would go into
wsrmp-1.1-spec-wd-nn +1.
But wouldn’t the
editors work on wsrmp-1.1-spec-ed-nn and at
some point decide to bring that to the TC’s attention as
wsrmp-1.1-spec-wd-nn? So there would be many revisions of the ed-nn version
but not of the wd-nn version. I see that going through many ed revisions and
then going to a wd version with no revisions would be more work. More
importantly its more use of Kavi as well which I certainly see as a bigger
pain. So if that sounds like a hassle then don’t worry about it.
My concern was how
the TC would view many revisions on a given wd, it seems weird. As long as
it doesn’t change once the TC starts reviewing it and pointing to it I don’t
see any real problem.
From:
Gilbert Pilz [mailto:Gilbert.Pilz@bea.com]
Sent: Thursday, October 27, 2005 8:11
PM
To:
ws-rx-editors@lists.oasis-open.org
Subject: RE: [ws-rx-editors] Document
titles and revision management
That's not
what we agreed to at the last F2F. We agreed that we didn't want bother the
group with constantly changing WD versions (Monday wd-03, Tues wd-04 and
wd-05, Thu wd-06). We also agreed that we didn't want to create confusion by
only showing the group "certain" WDs (wd-05 followed by wd-23) as it would
be difficult to follow which WD followed which from the TC's perspective
(was wd13 the "next" WD after wd05 or was that wd09?). One of the reasons we
wanted CVS was to track multiple revisions of the same WD version. Without
CVS we have decided to use Kavi like CVS by maintaining multiple revisions
of the same WD version.
-
g
From:
Marc Goodner [mailto:mgoodner@microsoft.com]
Sent: Thursday, October 27, 2005 6:06
PM
To: Gilbert Pilz;
ws-rx-editors@lists.oasis-open.org
Subject: RE: [ws-rx-editors] Document
titles and revision management
I think what you
want is a title like wsrmp-1.1-spec-wd-02 with no revisions in Kavi at
all. When you get to wsrmp-1.1-spec-wd-03 you would then move the old one
to the other folder to reduce directory
clutter.
I don’t believe
there ever should be more than one version of a doc like
wsrmp-1.1-spec-wd-nn. I would think any check in would rev the nn.
Otherwise how could line numbers stay consistent after you edit on version
of wsrmp-1.1-spec-wd-nn and then check in
another?
I can see the
argument against using Kavi’s versioning and not creating a single title
like wsrmp-1.1-spec-wd and then only displaying the nn within the doc (I
would assume it should match the Kavi revision number). Note that is how I
am managing the issue list during this migration to the stable url.
However I can’t imagine someone really wanting revision 05 vs. 07 of that
but I definitely see the need for the specs.
From:
Gilbert Pilz [mailto:Gilbert.Pilz@bea.com]
Sent: Thursday, October 27, 2005 3:45
PM
To:
ws-rx-editors@lists.oasis-open.org
Subject: [ws-rx-editors] Document
titles and revision management
Currently in the WS-RX Editors
SC area of Kavi we seem to have adopted two methods of title/revision
management. The WSRM spec has a single title (WSRM 1.1 Editors Draft) that
does not contain any details about versions etc. Under this Kavi title you
can find versions of both wsrm-1.1-spec-04 and wsrm-1.1-spec-05 (the fault
lies with me, I checked in the first version of wd-05 under the same
title).
The WSRMP spec, on the other
hand, is titled "wsrmp-1.1-spec-wd-01.sxw". Under this title you will only
find versions of wsrmp-1.1-spec-wd-01. Umit informs me that, when
wsrmp-1.1-spec-wd-02 is created, she intends to create a corresponding
Kavi title to be used for all versions of wd-02 and so on . .
.
"What's it going to be then,
eh?"
I'm leaning towards Umit's
method since it makes it easier to find individual wd-xx versions without
having to dig through the history of a single Kavi title. We can keep the
"Calendar Documents" folder clean by rolling off old titles into an "Old
Titles" folder.