RE: [ws-rx-editors] Document titles and revision management

One little comment inline . . .

  

  
  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. 

  
 

  
<GP> I remember at 
  the last F2F we decided to "promote" from the editors repository to the TCs 
  repository based on a consensus of when it seemed like we had "enough stuff" 
  to promote. We specifically rejected the idea of promoting on a regular 
  schedule since we didn't want to end up putting out a "wd-0n" and "wd-0n+1" 
  that didn't have any differences between them.  

  
 

  
--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