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:]
Sent: Friday, October 28, 2005
9:41 AM
To: Marc Goodner; Gilbert Pilz;
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:]
Sent: Thursday, Oct 27, 2005 9:47 PM
To: Gilbert Pilz;
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:]
Sent: Thursday, October 27, 2005
8:11 PM
To:
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:]
Sent: Thursday, October 27, 2005
6:06 PM
To: Gilbert Pilz;
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:]
Sent: Thursday, October 27, 2005
3:45 PM
To:
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.
Comments?
- g
