[publican-list] RFC: Revision History & package versioning changes

[Steven Levine]

I want to be sure I understand this:

Jeffrey Fearn wrote:

 > 1: Package versions.
 >>
 >> Instead of using a combination of edition and pubsnumber for the
 >> package version and revision, we will use the first revnumber in the
 >> Revision History. Edition and pubsnumber would then be free to be used
 >> in the normal publishing way.
 >>

Does this mean that for every draft build we will need to increment the 
revnumber in the Revision_History.xml file the way we now increment the 
pubsnumber in the Book_Info.xml file?

Or -- and this I'm really not clear on -- the create_rev command will 
edit the revision history?

Either way, that would mean that there will be huge gaps in the 
numbering for the actual published versions, if we update a document 
between point releases. So, for example, the first 5.6 version of a 
document on redhat.com would be 5.6-1, and the next 5.6 version of a 
document on redhat.com could well be 5.6-14. Is that correct?

I'm not sure whether I think this is important or not, but I wanted to 
be sure I understood the implications here.

-Steven







> All tyranny needs to gain a foothold is for people of good conscience to 
> remain silent.
> - Thomas Jefferson
> 
> These changes have been committed to the SVN repository. User Guide 
> updates to follow.
> 
> Cheers, Jeff.
> 
> Jeffrey Fearn wrote:
>> Hi, due to translation packaging issues [1] and DocBook 5 removing 
>> pubsnumber [2] I am looking in to these two areas.
>>
>> I have come up with an approach that couples the two changes together, 
>> to create a standard approach to revision histories and package 
>> versions across all languages and DocBook versions.
>>
>> Please feel free to comment on this proposal.
>>
>> 1: Package versions.
>>
>> Instead of using a combination of edition and pubsnumber for the 
>> package version and revision, we will use the first revnumber in the 
>> Revision History. Edition and pubsnumber would then be free to be used 
>> in the normal publishing way.
>>
>> revnumber would be assumed to be two strings separated by a hyphen, 
>> with the left string being the version and the right string, including 
>> any other hyphens, being the revision.
>>
>> e.g. <revnumber>1.0-14</revnumber> would be version 1.0, revision 14.
>>
>> The current behavior of using cfg file parameters before using XML 
>> sources would continue. i.e. setting version in publican.cfg would 
>> supersede any settings in Revision_History.xml.
>>
>>
>> 2: Translation Revision Histories
>>
>> Currently there is no way for translation histories to be documented. 
>> This prevents tying translation packages to bugzilla or tracking when 
>> or by whom translations were supplied.
>>
>> To allow translation histories to be maintained we will add an XML 
>> file in to the translated language directories. This file will be 
>> named Revision_History.xml and will be of the same structure as the 
>> source language file, however it will only contain revisions of that 
>> language.
>>
>> It is suggested that translations revnumbers will be the same as the 
>> source it was based off, with the addition of a decimal place and an 
>> incrementing digit.
>>
>> e.g. if the source revnumber was <revnumber>1.0-14</revnumber> then 
>> the translation revnumbers would start at 
>> <revnumber>1.0-14.1</revnumber> and increment from there.
>>
>> We use a decimal point to ensure fedora packaging rules for change log 
>> entries are met.
>>
>> It is proposed that when update_po is run each language affected would 
>> have a new revision added detailing this fact and setting the new 
>> revnumber as suggested above, current source language revnumber + '.1'.
>>
>> When building translated documentation the source and translation 
>> revision histories will be merged and sorted to present a unified 
>> history for the translated document.
>>
>> This change would remove the current requirement of using the 
>> <lang-loc>/Book_Info.po file to contain the translation revision number.
>>
>>
>> 3: Tooling
>>
>> To aid automation and general use we will add extra functionality to 
>> publican.
>>
>> A: Add create_rev action to publican CLI
>>
>> A new action, create_rev, will be added to publican to allow authors, 
>> and translators, to add a full revision from the command line.
>>
>> Proposed parameters:
>>   --date        set a specific date, default to today if not set
>>   --revnumber   set a specific revnumber, will use latest + 1 in not set
>>         for translations it would be latest + .1
>>   --lang        the language to update
>>   --change      the change made (multiples of these may be specified)
>>
>> The author details required for each revision will be fetched from a 
>> user configuration file. [see B]
>>
>> B: Add create_user option to publican CLI
>>
>> Entering author details on the command line will become laborious and 
>> error prone, it should be possible to enter these details once and 
>> then used when required.
>>
>> A new new action, create_user, will be added to publican to allow 
>> author details to be entered and saved in to a configuration file for 
>> later use.
>>
>> Proposed parameters:
>>   --firstname   users first name
>>   --surname     users surname
>>   --email       users email address
>>
>>
>> [1] https://bugzilla.redhat.com/show_bug.cgi?id=642127
>> [2] http://www.docbook.org/specs/docbook-5.0-spec-cs-01.html#s.remvlegacy
>>
>>
>> Cheers, Jeff.
>>
> 
>