[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

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

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 redhat com>
Software Engineer
Engineering Operations
Red Hat, Inc
Freedom ... courage ... Commitment ... ACCOUNTABILITY

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]