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

[Jeffrey Fearn]

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