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

[Ruediger Landmann]

On 12/18/2010 01:18 AM, Steven Levine wrote:
> 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?

Yes, exactly. Publican 3.0 looks to the Revision_History.xml file to 
generate the Version and Release parameters of the package name and the 
%changelog entry in the package spec file. The <edition> and 
<pubsnumber> will finally be completely decoupled from the packaging 
process -- we were abusing these tags previously.

This new mechanism also ensures that we always generate a valid RPM 
package -- where the package NVR and the specfile %changelog match -- 
which we have not been doing up to now, and which is essential for 
greater automation of the publishing process.

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

And yes, publican add_revision does indeed edit Revision_History.xml. It 
can:

* automatically add your name and email address (taken from a new 
configuration file)
* automatically add the date of the revision
* automatically increment the release number
* provide one or more lines of descriptions for the revision

For example:

publican add_revision --lang=en-US --member="Describe the new parameter 
BZ#123456" --member="Correct error in description of configuration 
option BZ#246810"

There is no longer any need to touch Book_Info.xml at all unless 
deliberately specifying a new edition, or to edit Revision_History.xml 
manually. (Although you can still edit Revision_History.xml manually if 
you prefer.)

Using the --lang parameter, translators can add revision numbers that 
will appear only in the version of the book translated in that language

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

Yes, just the same as now, and just the same as for any software 
component. So this is not a change.

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

Correct (and again, just the same as now) although this isn't a good 
example because it conflates the versioning of the document with the 
versioning of the software that it documents.

A clearer example might be that the first version of the Red Hat 
Enterprise Linux 5.6 Configuration Guide published publicly might be 
version 1.0-1 of the document and the next version published publicly 
might be 1.0-14, where versions 1.0-2 through 1.0-13 were development 
versions built and perhaps published internally but never released.

Cheers
Rudi