Bug 489626

Summary: Publican no longer allows for numbers in book titles
Product: [Community] Publican Reporter: Isaac Rooskov <irooskov>
Component: publicanAssignee: Jeff Fearn <jfearn>
Status: CLOSED CURRENTRELEASE QA Contact: Content Services Development <ecs-dev-list>
Severity: urgent Docs Contact:
Priority: urgent    
Version: 2.0CC: dmison, irooskov, jwulf, lbrindle, mhideo, mmcallis, publican-list, yshao
Target Milestone: ---Keywords: Documentation
Target Release: ---   
Hardware: i386   
OS: Linux   
Whiteboard:
Fixed In Version: 0.44 Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: 2009-03-12 02:30:25 EDT Type: ---
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:

Description Isaac Rooskov 2009-03-10 20:07:44 EDT
Description of problem:
Publican no longer allows for numbers in book titles

For the JBoss EAP the only way to distinguish between CP releases is by placing the version in the book title, this is because of Publican limitations with other fields.

Now, with the latest update to Publican, this is not possible causing all prior documentation for the JBoss EAP unbuildable for customers. 

If this fix does stay then not only will past documentation not be buildable, but there will be no way to distinguish between CP releaes of JBoss products meaning that the documentation on redhat.com/docs (and in the new documentation website yet to be releaesd), every time there is a CP release the documentation will have to be over-written with the new versions for the current CP. 

This further means that documentation for CP releases other than the current release will no longer be avaliable to customers, which our customers have already remarked in the past as a situation that would be unacceptable. 

I understand that Red Hat Enterprise Linux does not encounter this issue and that JBoss should change their naming conventions, but that does not mean that it is going to happen and because of this we do have to support the JBoss may (at least for the moment) in order to support our customers.

Version-Release number of selected component (if applicable):

Publican Version 0.43 Release 0.e15

How reproducible:

100%

Steps to Reproduce:
1. Checkout https://svn.jboss.org/repos/jbossas/projects/docs/enterprise/4.2.6/Getting_Started
2. in a terminal type the command 'make html-en-US' 
3. title error occurs and book no longer builds
  
Actual results:

The book does not build

Expected results:

Allow the book to build with numbers in the title. 

Additional info:

I understand that this update to Publican is considered a fix, however it could do it before and did not affect anyone adversely so I cannot see any harm in allowing it to be able to do it again.
Comment 1 Lana Brindley 2009-03-10 22:47:10 EDT
+1

I use numbers in titles for relnotes. In MRG, any books (mostly relnotes) released for minor releases (x.y.z) get collapsed into the major release's directory (x.y). This means we need to able to specify which minor release the book is for. We can't have four books all titled "Release Notes" floating around in one directory. Using other naming conventions ("Release Notes Security Release"; "Release Notes Enhancement Release") is not only confusing for the customer and the maintainer, but also very limited in scope (When you already have a "Release Notes Security Release" for 1.1.1, what do you call the security release for 1.1.4?).

</$0.02>

LKB
Comment 2 Jeff Fearn 2009-03-10 23:50:32 EDT
(In reply to comment #1)
> +1
> 
> I use numbers in titles for relnotes. In MRG, any books (mostly relnotes)
> released for minor releases (x.y.z) get collapsed into the major release's
> directory (x.y). This means we need to able to specify which minor release the
> book is for. We can't have four books all titled "Release Notes" floating
> around in one directory. Using other naming conventions ("Release Notes
> Security Release"; "Release Notes Enhancement Release") is not only confusing
> for the customer and the maintainer, but also very limited in scope (When you
> already have a "Release Notes Security Release" for 1.1.1, what do you call the
> security release for 1.1.4?).
> 
> </$0.02>
> 
> LKB  

Changing the name (title) for each revision means that users of the Desktop content will NOT get updated documentation when they upgrade because you are changing the package name.

---

e.g.

I install version 1.0 of foo + foo-release-notes

I upgrade to foo 1.1; the release notes didn't get updated because the package name changed and I don't have the renamed package installed. Now the release notes I'm reading are out of synch with the program.

---

In addition you are going to be incurring an increasing maintenance burden every z stream release. Each package you ship has to be maintained for 7 years, and because you are effectively forking the package every Z stream, that is one more package on your list for the next 7 years.

This scenario is the reason this restriction was introduced. Over time it creates a massive, ongoing, unavoidable maintenance effort. Do you really want to have 7 versions of your release notes package in Bugzilla and have to port fixes between them?

However, there are good reasons for allowing numbers in titles. Isaac, Brian and I cornered Mike and have this policy changed, so a patched version will be coming out soon.

I'd seriously reconsider using this facility for the use you specified above.

Cheers, Jeff.
Comment 3 Lana Brindley 2009-03-11 19:09:00 EDT
Jeff,

I really don't understand the point you're trying to make here. Why would having numbers in the title prevent users from getting the package? It appears as though they wouldn't get the package regardless, from your example. Also, as far as packages go, surely the package exists regardless of its title, and therefore needs maintenance?

Sorry, I'm not trying to be facetious, I just don't understand, and would like to. If there's a better way of doing things, then I'm all for it!

L
Comment 4 Jeff Fearn 2009-03-11 19:26:32 EDT
(In reply to comment #3)
> Jeff,
> 
> I really don't understand the point you're trying to make here. Why would
> having numbers in the title prevent users from getting the package?

It's about upgrading, when you change the name you have a new package; so they don't get updated content when they run yum update.

> It appears
> as though they wouldn't get the package regardless, from your example.

"I install version 1.0 of foo + foo-release-notes" where foo-release-notes is your docs package.

> Also, as
> far as packages go, surely the package exists regardless of its title, and
> therefore needs maintenance?

If you update the content without changing the name you have 1 package to maintain, and you are actively maintaining it every release. If you rename it you have many packages to maintain and you have to ensure you back port any relevant fixes.

Cheers, Jeff.
Comment 5 Lana Brindley 2009-03-11 19:41:21 EDT
So you're suggesting that we should have one relnote per x.y release, and just change the content of it for every x.y.z release?

Doesn't that cause a major problem with historical reference? What about if someone is running foo 1.1.1 and the only available relnotes are for foo 1.1.3 (Because the 1.1.1 relnotes got updated to 1.1.2 and then 1.1.3)?

What about the circumstance where someone updates to 1.1.2, finds issues and rolls back to 1.1.1? How do they find out what potential issues they may be rediscovering by doing that?

As for maintenance, they're relnotes - by definition, they only apply for that release (minor or otherwise), so there's not really an ongoing maintenance issue. I can see where the problem might lie in doing that with books, but that's why I don't do books like that ;)

Unless I've completely missed your point (again)?

L
Comment 6 Fedora Update System 2009-03-18 19:56:55 EDT
publican-fedora-0.18-0.fc10,publican-0.44-0.fc10 has been submitted as an update for Fedora 10.
http://admin.fedoraproject.org/updates/publican-fedora-0.18-0.fc10,publican-0.44-0.fc10
Comment 7 Fedora Update System 2009-03-26 10:53:01 EDT
publican-fedora-0.18-0.fc10, publican-0.44-0.fc10 has been pushed to the Fedora 10 stable repository.  If problems still persist, please make note of it in this bug report.