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

[Jeffrey Fearn]

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


-- 
Jeff Fearn <jfearn at redhat.com>
Software Engineer
Engineering Operations
Red Hat, Inc
Freedom ... courage ... Commitment ... ACCOUNTABILITY