Bug 476471

Can you please provide an URL to the spec file? It's much easier for possible reviewers to have a look at it.

Some quick comments on your spec file:

- The name of this package is a bit wired.  Upper case, underscore, version, and language. According the other doc stuff (e.g. fedora-release-notes) 'fedora-security-guide' would be nice or 'linux-security-guide'.

- 'Source0:' should point to the upstream source location, if possible.

- About the .desktop file.  The guidelines says that it should be include as
'SourceX:' https://fedoraproject.org/wiki/Packaging/Guidelines#Desktop_files
 See 'desktop-file-install usage' for details about the installation of this file.  Get in touch with upstream and ask them to include the .desktop file. 

- There is no entry in your %changelog section
  https://fedoraproject.org/wiki/Packaging/Guidelines#Changelogs

Spec URL: http://sparks.fedorapeople.org/linux-security-guide.spec

Noted on the naming.  Will change it to either fedora-security-guide or linux-security-guide (probably latter).

An update:
Spec URL: http://sparks.fedorapeople.org/linux-security-guide.spec
SRPM URL: http://sparks.fedorapeople.org/fedora-Linux_Security_Guide-10-en-US-1.0-3.src.rpm

- The spec file name and the SRPM name are different.
- Changelog entries are still missing.
  https://fedoraproject.org/wiki/Packaging/Guidelines#Changelogs
- URL should be https://fedorahosted.org/securityguide/
- Source0 should be point to the upstream source location, to the source tarball to be more precise.
  Please refer to https://fedorahosted.org/web/faq, Section 'How can I publish archive releases (tgz, zip, etc) for my project?'
- If there are no 'BuildRequires:' or 'Requires:' leave those entries away.
- Isn't this package 'BuildArch: noarch' ?
- The license should be only 'Open Publication'
  See https://fedoraproject.org/wiki/Licensing#Good_Licenses_2
- Your %file section seems to be unfinished 


I'm not able to rebuild your package on Fedora 9.

*ERROR: Brand fedora is not installed*
Either install fedora or change to a valid Brand.
Installed Brands: echo common
make: *** [pre] Error 1


The rpmlint output of the SRPM:

[fab@laptop024 SRPMS]$ rpmlint fedora-Linux_Security_Guide-10-en-US-1.0-3.src.rpm 
fedora-Linux_Security_Guide-10-en-US.src: W: mixed-use-of-spaces-and-tabs (spaces: line 3, tab: line 2)
fedora-Linux_Security_Guide-10-en-US.src: E: no-changelogname-tag
fedora-Linux_Security_Guide-10-en-US.src: W: invalid-license Open Publication License
1 packages and 0 specfiles checked; 1 errors, 2 warnings.


For translations, take a look at https://translate.fedoraproject.org/submit/maintainers/info

- The spec file name and the SRPM name are different. FIXED
- Changelog entries are still missing. IN PROGRESS (PUBLICAN BROKEN)
- URL should be https://fedorahosted.org/securityguide/ FIXED
- Source0 WE ARE DEVELOPING THIS DOCUMENT.
- If there are no 'BuildRequires:' or 'Requires:' FIXED
- Isn't this package 'BuildArch: noarch' ? YES
- The license should be only 'Open Publication' FIXED (PUBLICAN BROKEN)
- Your %file section seems to be unfinished ???

Spec URL: http://sparks.fedorapeople.org/fedora-Linux_Security_Guide-10-en-US.spec
SRPM URL: http://sparks.fedorapeople.org/fedora-Linux_Security_Guide-10-en-US-1.0-3.src.rpm

Latest version...

Spec URL:
http://sparks.fedorapeople.org/fedora-Linux_Security_Guide-10-en-US.spec
SRPM URL:
http://sparks.fedorapeople.org/fedora-Linux_Security_Guide-10-en-US-1.0-4.src.rpm

(In reply to comment #4)
> *ERROR: Brand fedora is not installed*
> Either install fedora or change to a valid Brand.
> Installed Brands: echo common
> make: *** [pre] Error 1

Presumably "BuildRequires: publican-fedora" is required.

(In reply to comment #5)
> - Changelog entries are still missing. IN PROGRESS (PUBLICAN BROKEN)

Fabian is referring to the spec file changelog entries.

> - Source0 WE ARE DEVELOPING THIS DOCUMENT.

You should still publish an url (preferred) or explain in the spec file how it is generated:
http://fedoraproject.org/wiki/Packaging/SourceURL

(In reply to comment #6)
> Latest version...
> 
> Spec URL:
> http://sparks.fedorapeople.org/fedora-Linux_Security_Guide-10-en-US.spec
> SRPM URL:
> http://sparks.fedorapeople.org/fedora-Linux_Security_Guide-10-en-US-1.0-4.src.rpm

I think you don't need the 10 in the package name.  Presumably you are not planning to have a new fedora-Linux_Security_Guide-11-en-US in F11, etc?

I still liked fedora-security-guide or linux-security-guide.

Once translations are available presumably they would go into separate source packages.

One problem is the package naming scheme.  Publican used <brand>-<title>...  That means we can have fedora-Security_Guide but not fedora_Security_Guide.  Not sure how to go forward with this.  Maybe Publican can be modified to do <brand>_<title> instead.

Latest version...

Spec URL: 
http://sparks.fedorapeople.org/fedora-Linux_Security_Guide-.-en-US.spec

SRPM URL:
http://sparks.fedorapeople.org/fedora-Linux_Security_Guide-.-en-US-1.0-5.src.rpm

Hi Jens,

Given this:
https://bugzilla.redhat.com/show_bug.cgi?id=478946

Can we still use capitalization in the package name so we can preserve the 1-to-1 correspondence with the top level xml file and <title> tag names?

- Mike

[was writing this yesterday]

(In reply to comment #8)
> One problem is the package naming scheme.  Publican used <brand>-<title>... 
> That means we can have fedora-Security_Guide but not fedora_Security_Guide. 
> Not sure how to go forward with this.  Maybe Publican can be modified to do
> <brand>_<title> instead.

I don't see any problem with fedora-Security_Guide (vs fedora_Security_Guide).  However the naming issue really comes down to whether we should follow the publican naming scheme verbatim in this case.  IMHO it would also be ok to name this package fedora-security-guide, but I would be happy to hear opinions from other packager reviewers too, since this is a test case as the first guide in publican going into fedora AFAIK.  Having said that in order to avoid having to repeat this discussion for every publican documentation and translation package review it would probably be better if publican could generate lower-cased tarballs IMHO.

http://fedoraproject.org/wiki/Packaging/NamingGuidelines#Separators
http://fedoraproject.org/wiki/Packaging/NamingGuidelines#Case_Sensitivity

(In reply to comment #9)
> http://sparks.fedorapeople.org/fedora-Linux_Security_Guide-.-en-US.spec
> http://sparks.fedorapeople.org/fedora-Linux_Security_Guide-.-en-US-1.0-5.src.rpm

Erm, -.- is not good.

Does publican generate the spec file?

Still no changelog in .spec and what about the .desktop file?

I would suggest starting something like this and fixing the the FIXME's:
http://koji.fedoraproject.org/koji/getfile?taskID=1037394&name=fedora-Linux_Security_Guide-en-US-1.0-5.src.rpm

I guess publican needs some way not to have a version in the doc name.

I tried building on F10 and ran into:

Processing, Product: fedora, Version: ., Edition: 1.0, Release: 5
START: xml-en-US Wed Jan  7 15:52:34 EST 2009
        copying fedora/en-US  Common_Content
cleaning files
        7_Zip.xml
Can't locate XML/TreeBuilder.pm in @INC (@INC contains: /usr/lib64/perl5/5.10.0/x86_64-linux-thread-multi /usr/lib/perl5/5.1\
0.0 /usr/local/lib64/perl5/site_perl/5.10.0/x86_64-linux-thread-multi /usr/local/lib/perl5/site_perl/5.10.0 /usr/lib64/perl5\
/vendor_perl/5.10.0/x86_64-linux-thread-multi /usr/lib/perl5/vendor_perl/5.10.0 /usr/lib/perl5/vendor_perl /usr/local/lib/pe\
rl5/site_perl /usr/local/lib64/perl5/site_perl .) at /usr/bin/xmlClean line 43.
BEGIN failed--compilation aborted at /usr/bin/xmlClean line 43.
make: *** [xml-en-US] Error 4
error: Bad exit status from /var/tmp/rpm-tmp.rQtsc2 (%build)

Does perl-XML-TreeBuilder need to be rebuilt in f10?

Scratch build in koji buildsystem however is successful:
http://koji.fedoraproject.org/koji/taskinfo?taskID=1037394

(In reply to comment #12)
> (In reply to comment #9)
> > http://sparks.fedorapeople.org/fedora-Linux_Security_Guide-.-en-US.spec
> > http://sparks.fedorapeople.org/fedora-Linux_Security_Guide-.-en-US-1.0-5.src.rpm
> 
> Erm, -.- is not good.
> 
> Does publican generate the spec file?

It can.  The spec file that I have listed is the one that is generated by publican.

(In reply to comment #13)
> Still no changelog in .spec and what about the .desktop file?

Apparently this is being addressed in the latest version of publican.  Still waiting to see the update, however.

Hmm, well there is no need to wait for publican to improve its default .spec files.  It will not be possible to use it post review anyway since the spec file needs to carry changelog info and the release number will be bumped the package is rebuilt/updated etc.

If want this review to move ahead you need to start incorporating the suggestions made above so far.  If you are able to do that then I am willing to offer to sponsor you pending the successful completion of this review.

I forgot to use the dist tag in the release field of my scratch build yesterday - here is a better spec to fix that:

http://petersen.fedorapeople.org/fedora-Linux_Security_Guide-en-US.spec

Latest version...

Spec URL: 
http://sparks.fedorapeople.org/fedora-security-guide-11-en-US.spec

SRPM URL:
http://sparks.fedorapeople.org/fedora-security-guide-11-en-US-1-6.src.rpm

Eric, do we agree that we can't have the fedora version number (11) in the package name?

And what about comment 18?

(In reply to comment #20)
> Eric, do we agree that we can't have the fedora version number (11) in the
> package name?
> 
> And what about comment 18?

Yes.  I forgot to manually change that.  Publican can't seem to do the fc11 thing.  

I manually put the changelog information in the .SPEC file but I don't know how to put it in so that it will show up in the SRPM.

I am afraid you need to drop the publican generated spec file going on and start to learn how to edit it yourself: I encourage to start from my version above or merge my changes into your latest one.

You can create an srpm with "rpmbuild -bs fedora-security-guide-en-US.spec" say.

(In reply to comment #22)
> I am afraid you need to drop the publican generated spec file going on and
> start to learn how to edit it yourself: I encourage to start from my version
> above or merge my changes into your latest one.
> 

Hi Jens,

Can you give us a list of things publican needs to do wrt to specfiles/changelogs/packagenaming?


Cheers,
Mike

> Can you give us a list of things publican needs to do wrt to
> specfiles/changelogs/packagenaming?

The thing at the moment I see is the product versioning issue which doesn't really make sense for Fedora I think.  Well maybe it could in some cases - then the version should just go into the package version field ("Fedora 11 Foo Bar manual" -> fedora-Foo_Bar_Guide-en-US-11-5.fc11 say).  Otherwise if the version is not linked to the Fedora release version it should not appear in the tarball, name, etc.

Also for Fedora usually English is assumed for documentation, and since it seems to be the base language for our docs, I would probably suggest dropping "en-US" from base doc package name.

Let me ask on fedora-packaging list about the naming though too.

Additional questions: is the documentation Fedora specific?  Does it need to be Fedora branded at all?

It should be.

I had a quick look through http://sparks.fedorapeople.org/security-guide.pdf and noticed that section 1.5. "Security Updates" seems currently to be quite specific to Red Hat not Fedora (some of it may have applied for Fedora Core in the past), so it would be good to rework it for the Fedora version: otherwise it all looks fairly generic to me so far, but I would have to read it all through carefully to be sure.  If that is the case then maybe it does not have to be fedora branded?

(In reply to comment #26)
> It should be.

Hmm, please explain a little more. :)

Ah nevermind, I see now it is needed for Fedora to appear as the product name through the document of course.

(In reply to comment #29)
> Ah nevermind, I see now it is needed for Fedora to appear as the product name
> through the document of course.

Well that is not actually true: product and brand are separate in publican config.

Okay, I'm getting excited now.  Thanks to the new version of publican I now have an SRPM and a SPEC file that look good (I think) and the rpmbuild passes the rpmlint test.

SPEC URL: http://sparks.fedorapeople.org/fedora-security-guide-11-en-US.spec

SRPM URL: http://sparks.fedorapeople.org/fedora-security-guide-11-en-US-1.0-6.fc10.src.rpm

Updated the files...  Builds clean, still.

SPEC URL: http://sparks.fedorapeople.org/fedora-security-guide-11-en-US.spec

SRPM URL: http://sparks.fedorapeople.org/fedora-security-guide-11-en-US-1.0-7.fc10.src.rpm

The package name still contains the version number which is bad.

How about fedora-security-guide-en-US-11-7.fc10 ?

(In reply to comment #33)
> The package name still contains the version number which is bad.
> 
> How about fedora-security-guide-en-US-11-7.fc10 ?

At the risk of sounding dumb...  Why are version numbers bad?  If anything the "11" is something I don't like but the version "1.0-7" seems like a really good idea.

I've already filed a ticket against the "11" part (https://bugzilla.redhat.com/show_bug.cgi?id=478950) but not sure where that is.  I can manually remove it from the package if that makes everything right.

> At the risk of sounding dumb...  Why are version numbers bad?  If anything the
> "11" is something I don't like but the version "1.0-7" seems like a really good
> idea.

Yep, the version number in the package name itself is bad...
ie the "-11" part in the Name field:

Name:	fedora-security-guide-11-en-US

This has already come up several times in the review.
Source (base) package names are stable in fedora over releases.

(I am happy to discuss the packaging on irc if I can make things clearer.)

> I can manually remove it from the package if that makes everything right.

That would help.

(In reply to comment #35)
> Yep, the version number in the package name itself is bad...
> ie the "-11" part in the Name field:

Okay, consider the -11 gone.

SPEC URL: http://sparks.fedorapeople.org/fedora-security-guide-en-US.spec

SRPM URL:
http://sparks.fedorapeople.org/fedora-security-guide-en-US-1.0-7.fc10.src.rpm

Okay, lots of work today.  Fixed the code (at least on my end) to remove the %PRODUCTNUMBER from the SPEC which also removes it from the package name.

Here are links to the latest and greatest:

SPEC URL: http://sparks.fedorapeople.org/fedora-security-guide-en-US.spec

SRPM URL: http://sparks.fedorapeople.org/fedora-security-guide-en-US-1.0-10.fc10.src.rpm

Verified to be clean with rpmlint.

Thanks.

Koji scratch build is successful:
http://koji.fedoraproject.org/koji/taskinfo?taskID=1087751

I can sponsor you, Chris, based on a successful completion of this review. :)

You still need to address some earlier comments though:

(In reply to comment #1)
> - 'Source0:' should point to the upstream source location, if possible.
> 
> - About the .desktop file.  The guidelines says that it should be include as
> 'SourceX:' https://fedoraproject.org/wiki/Packaging/Guidelines#Desktop_files
>  See 'desktop-file-install usage' for details about the installation of this
> file.  Get in touch with upstream and ask them to include the .desktop file. 

(In reply to comment #4)
> - URL should be https://fedorahosted.org/securityguide/
> - Source0 should be point to the upstream source location, to the source
> tarball to be more precise.
>   Please refer to https://fedorahosted.org/web/faq, Section 'How can I publish
> archive releases (tgz, zip, etc) for my project?'

I guess since this is Fedora only, all the htmlview stuff is not needed in the spec file and the desktop file should use xdg-open.

(In reply to comment #38)
I have filed a bug against Publican for the Source0 entry (482968).  I cannot hard code this in as I previously though.

Am also trying to figure out how to populate the .desktop file with the proper options as I know it shows up on the computer with the proper icons and such.  Will file a bug if I can't figure it out.


(In reply to comment #39)
I can hard code the htmlview only but it would most likely break functionality in Publican later.  Is this a hard requirement?  It doesn't appear to hurt the package as it is an if statement.

> (In reply to comment #39)
> I can hard code the htmlview only but it would most likely break functionality
> in Publican later.  Is this a hard requirement?  It doesn't appear to hurt the
> package as it is an if statement.

You mean the conditional stuff - yeah we can probably live with that if we are proceeding with pure publican generated spec files.

But htmlview vs xdg-utils stuff should be fully conditionalized not partly like now.

(In reply to comment #41)
Well, it looks something like this in the code:

%if %{HTMLVIEW}
Requires:	htmlview 
%else 
Requires:	xdg-utils
%endif


(In reply to comment #38)
Apparently the .desktop file is "retarded stuff" and won't be fixed.  I'm not sure what information goes into the file so I can't build one myself.  Will need some help with this one.

The point I was trying to get at is that you have the conditional but then the desktop file just uses htmlview anyway. ;-)

I suggest starting by copying the .desktop to a file (Source1) and including that in the srpm.

(In reply to comment #43)
> The point I was trying to get at is that you have the conditional but then the
> desktop file just uses htmlview anyway. ;-)

Yeah, I'm not sure why it is in there but it might be another "feature" that I'd have to break.  Doesn't look like it is going to hurt anything.


> I suggest starting by copying the .desktop to a file (Source1) and including
> that in the srpm.

Oh!  Okay, that's been done and the source tgz has been uploaded.

If you have new urls, please post them here.

SPEC: http://sparks.fedorapeople.org/fedora-security-guide-11-en-US.spec

SRPM: http://sparks.fedorapeople.org/fedora-security-guide-11-en-US-1.0-12.fc10.src.rpm

I don't want to say but the version number is back in the file names again...

Of course, and it will until a major rewrite of Publican occurs.  Apparently this is how all RH Publican packages appear.

Erm, I have a sense of deja vu...

so what are you proposing to call the package again?

Created attachment 334897 [details]
Using Fedora Versioned RPM Names Afford Functionality

Jens,

Attached is a screenshot of a practical use case where we are using installing different versions of the fedora security guide on the same distro. By having separate Fedora versioned packages, system administrators can read and perform specific fedora release procedures. This saves them from having to install the Security Guide package on 3 different instances of Fedora. Does this make sense?

- Mike

> Attached is a screenshot of a practical use case where we are using installing
> different versions of the fedora security guide on the same distro. By having
> separate Fedora versioned packages, system administrators can read and perform
> specific fedora release procedures. This saves them from having to install the
> Security Guide package on 3 different instances of Fedora. Does this make
> sense?

Parallel install (ie having multiple versions installed) is really another issue.
I can see publican's way makes sense on RHEL but I am not sure on Fedora where we have
a new release every 6 months or so.  How many fedora-security-guide's do we want
to have in a fedora release?  Or maybe you are thinking about subpackaging.
The base package name does not have to determine the name of the package that is
installed.  I don't think we support installing multiple versions of the
fedora release-notes either say.

I am not recommending this, but fedora-security-guide could provide
a fedora-security-guide-11 package for F11, etc, allowing parallel install.
As I see it though there should only be one base package in Fedora and it should
be named "fedora-security-guide" (going by the current submission).
How fedora-security-guide.spec gets created is not really Fedora's problem.
Publican spec files are not that hard to write and could easily be scripted,
if publican can't do the Right Thing for Fedora packaging.

I see parallel installation as a corner-case and not something Fedora needs
go out of its way to support: IMHO most users would only want the latest version
of the guide installed - are the changes in security between Fedora releases
really that big?

But if the Fedora Packaging Committee can be persuaded that we need an exception
for Publican or approves packaging guidelines for publican packages that would
be fine.

(In reply to comment #51)
> > Attached is a screenshot of a practical use case where we are using installing
> > different versions of the fedora security guide on the same distro. By having
> > separate Fedora versioned packages, system administrators can read and perform
> > specific fedora release procedures. This saves them from having to install the
> > Security Guide package on 3 different instances of Fedora. Does this make
> > sense?
> 
> Parallel install (ie having multiple versions installed) is really another
> issue.
> I can see publican's way makes sense on RHEL but I am not sure on Fedora where
> we have
> a new release every 6 months or so.  How many fedora-security-guide's do we
> want
> to have in a fedora release?  

As many fedora platforms as the system administrators are administering.

Or maybe you are thinking about subpackaging.
> The base package name does not have to determine the name of the package that
> is
> installed.  I don't think we support installing multiple versions of the
> fedora release-notes either say.

If I could provide a metric that shows that people reading the fedora 10 release notes online are not running fedora 10, would you be supportive of this request?

> 
> I am not recommending this, but fedora-security-guide could provide
> a fedora-security-guide-11 package for F11, etc, allowing parallel install.
> As I see it though there should only be one base package in Fedora and it
> should
> be named "fedora-security-guide" (going by the current submission).
> How fedora-security-guide.spec gets created is not really Fedora's problem.
> Publican spec files are not that hard to write and could easily be scripted,
> if publican can't do the Right Thing for Fedora packaging.
> 
> I see parallel installation as a corner-case and not something Fedora needs
> go out of its way to support: IMHO most users would only want the latest
> version
> of the guide installed - are the changes in security between Fedora releases
> really that big?
> 
> But if the Fedora Packaging Committee can be persuaded that we need an
> exception
> for Publican or approves packaging guidelines for publican packages that would
> be fine.

Created attachment 335032 [details]
Fedora Platform as Base for Open Source Documentation

Hi Jens,

Looking outside of the current distro we are working on, the attached screenshot demonstrates the capabilities of this naming tracking system that uses Fedora as a platform development library. Does this make sense? Constraining to a single rpm for a single version for a single release does not afford flexibility of choice. Let me know if I am way off into the wild woods. - Mike

Hi Jens,

Yes I see now I am off in the wild woods. I see now how the .spec file is the point in time where the upstream meets the distro. Using the technology we have today, if we were to create a documentation policy that mapped VER to the release version of the software we are documenting I think we would be in good shape.

For example:

Turning this:
fedora-Security_Guide-10-en-US-1-12.fc10.noarch

Into:
fedora-Security_Guide-en-US-10-12.fc10.noarch

I think I got it in my head. Would that work?

- Mike

> Turning this:
> fedora-Security_Guide-10-en-US-1-12.fc10.noarch
> 
> Into:
> fedora-Security_Guide-en-US-10-12.fc10.noarch
> 
> I think I got it in my head. Would that work?

Sounds good to me. :-)

(In reply to comment #55)
> > Turning this:
> > fedora-Security_Guide-10-en-US-1-12.fc10.noarch
> > 
> > Into:
> > fedora-Security_Guide-en-US-10-12.fc10.noarch
> > 
> > I think I got it in my head. Would that work?
> 
> Sounds good to me. :-)  

thanks, Jens. 

lol, believe it or not, i just found out it would break the indexing tool we use to separate versions from editions. back to the drawing board. sorry for the distraction guys. - Mike

Thanks for trying Mike.  

Don't we have a precedent for this already?  We have version numbers (of a
sort) on compatibility libraries in Fedora, like "libsoup22" for instance, so
we can carry multiple parallel versions.

Can anyone clarify the difference between that situation and this?

If someone wants to work on Fedora 11 release notes in Fedora 10, and be able
to install them in parallel to see the results of their WIP, how would we
accomplish that, without having some distinction in the name of the package?

(In reply to comment #57)
> Don't we have a precedent for this already?  We have version numbers (of a
> sort) on compatibility libraries in Fedora, like "libsoup22" for instance, so
> we can carry multiple parallel versions.

We can do whatever we want... :) but do we really want to ship all the old relnotes in every release?
Can't people just read them on the web.

I am not veto'ing parallel install per se, but maybe it is worth considerng what is so special about docs packages that warrants/necessitates parallel install since we don't really do this for any other packages except libraries/tools needed occasionally for back-compatibility.

> Can anyone clarify the difference between that situation and this?

I guess libsoup22 was actually needed by one or more other packages in the distro?  (Looks like it could/should actually be dropped now though - nothing seems to need it anymore - which illustrates the problem of keeping old compat packages around.)

> If someone wants to work on Fedora 11 release notes in Fedora 10, and be able
> to install them in parallel to see the results of their WIP, how would we
> accomplish that, without having some distinction in the name of the package?  

Doesn't publican allow writers to create html/pdf file output for reviewing docs, etc without having to roll an rpm?

Are we going to do a new package review for every release? :)

The two main questions in my mind are:

1) What is the name of the .spec file?

2) What is the name of the base package?

The rest is just auxillary in my mind.

(In reply to comment #47)
> I don't want to say but the version number is back in the file names again...  

Please supply a link to the Packaging Guidelines where this ruls is detailed. I have searched and can not find it.

Assuming you mean the version appearing in the spec file name:

https://fedoraproject.org/wiki/Packaging/NamingGuidelines#Spec_file_name

Hi Spot,

I am not sure of the process, but i think we have a breakthrough here:
https://www.redhat.com/archives/fedora-docs-list/2009-March/msg00153.html

I think we have what could be seen as a waiver on the two issues but i don't know the process to follow through. Can you help navigate that?

Cheers,
Mike

I'm assuming you're referring to Toshio's statement that:

"Another option is to look at a streamlined set of review items for
publican-created doc packages... We've never explicitly done this but in
practice, people know they don't have to check, for instance, shared
library guidelines when writing and reviewing a pure python module."

Someone would first need to propose what the specific set of review items for publican-created doc packages should be. The way to do this is to create a wiki page under: https://fedoraproject.org/wiki/PackagingDrafts/

Once that is done, then add a link to the new page to the todo list for the Fedora Packaging Committee (FPC) by editing the table here: https://fedoraproject.org/wiki/PackagingDrafts/DraftsTodo

The FPC meets once every two weeks, and is scheduled to meet next Tuesday. If the FPC approves it, it will go to the Fedora Engineering Steering Committee (FESCo) for ratification. Once they ratify, then you could start opening publican doc packages for review under the new guidelines.

Hope that helps.

Thanks, Spot, 

That makes sense! I can see how it all coalesces and fits together in my head.

Eric, do you want to draft a policy for submission or would you like me to do it. I can have it done by Monday for your review if you like.

- Mike

(In reply to comment #64)
> Thanks, Spot, 
> 
> That makes sense! I can see how it all coalesces and fits together in my head.
> 
> Eric, do you want to draft a policy for submission or would you like me to do
> it. I can have it done by Monday for your review if you like.
> 

Josh has taken this on and drafted:
https://fedoraproject.org/wiki/Publican_Documentation_Packages

He has integrated it into the FPC agenda.
https://fedoraproject.org/wiki/PackagingDrafts/DraftsTodo

For your review. Thank you, Josh.

- Mike

Jens, FeSCO has approved the documentation naming guideline:

https://fedoraproject.org/wiki/Extras/SteeringCommittee/Meeting-20090403#FPC_report_-_2009-03-31

https://fedoraproject.org/wiki/PackagingDrafts/DocumentationNaming

Can you please approve this package now?

https://fedoraproject.org/wiki/Packaging:Minutes/20090331 contains the full discussion - note FPC explicitly expressed the hope that Fedora releases would not be flooded for multiple versions of every publican manual, unless it is really useful but deferred the individual decisions and burden to the Fedora Docs Project.

(For the record: I am disappointed that it was decided to push these two changes into Fedora Packaging Guidelines rather than fix the real problems in publican, but nevermind: embedding desktop files in spec files is also generally a bad idea since it basically make them hard to translate.)

So back to my questions in comment 59:

* what package are we reviewing here: fedora-security-guide or fedora-security-guide-11?  Note there is nothing to stop a fedora-security-guide.src source package from generating a fedora-security-guide-11.noarch binary package, though I don't recommend that personally.

If you go for the later base package name than you will have to do a new package review for every release, and how are you planning to deal with OS package upgrades? The versioned package should really obsolete the old package so that the new package will get installed on upgrades.  Hence making such parallel installs pretty useless: since rpm does not play well with parallel installs of packages that obsolete each other.  In this sense Fedora is a very different OS from RHEL.

Parallel packages is going to create a lot more work and packaging complexity - I warn you now here - it has already been well tried and is know (also from my personal experience) not to work well for RPM systems anyway.  I fear the approach may be building on sand or thin ice.

What you probably want and I would recommend is a base package called fedora-security-guide and then if you really want other version back or forward ported to a release they would be separate packages called fedora-security-guide-F10, etc, as Spot also suggested.  In practice I am skeptical if it would really be useful for this particular guide.

Also the kernel package for example is capable of parallel installs - in principle there is no reason why different versions of publican packages could not parallel installed too under the same name.

Things are worse than that though if you read the above FPC meeting log they further were opposed to individual publican packages per language (though I am not personally opposed to this) they believe there should be one big package with all the translations and then just subpackages for all the language.  While this would simplify the base package naming we know this is a bottleneck for building translations of manuals.  So taking that into account my overall recommendation at this early stage of fedora publican packaging is just to go with fedora-security-guide-en_US.spec and fedora-security-guide-en_US.noarch.  I don't see any win in including the OS version in the package names currently for fedora.

I just add a comment that I think it should be pretty trivial to write a small script to massage publican generated .spec into a form more suitable to Fedora than RHEL - so I don't feel having to use the publican .spec verbatim to simplify packaging for writers and translators is a requirement here.

Had a discussion with Jens to further understand his concerns. A solution would be do have the .src rpm w/o the version number but the resultant rpms would have the version number. This would ensure that the library system can still track the catalog. This would require a publican change and a policy change within documentation to sync the <productversion> with <edition> tags. Probably best then to remove the <edition> tags. I'll poll the teams to check on how editions are being handled.

fedora-Deployment_Guide-en-US-11-19.srpm
 |_ 
 | fedora-Deployment_Guide-11-web-en-US-11-19.rpm
 |_ 
   fedora-Deployment_Guide-11-desktop-en-US-11-19.rpm

http://petersen.fedorapeople.org/publican/publican-0.45-0.2+naming.fc11.noarch.rpm
is a test package with simplified srpm naming.

Then fedora publican can have a make target koji-en-US which would submit
fedora-security-guide-en-US-1.0-12.fc10.src to koji directly creating
fedora-security-guide-en-US-1.0-12.fc10.noarch.

BTW I thinking again about the naming: how about we just call the fedora package
Fedora-Security_Guide - that would bring it in line with standard publican
book naming I think.

Thanks again, Jens for the patch.

I have tested it in the build system, the indexer and the catalog systems and they are good! Well done!

I do have one concern that I need to talk to some folks about and that is how to coordinate who does the rpm rolling of translated content and how they are going to make sure that multiple writers/translators, accountable for multiple branches, don't clobber each other's rpms. I need to think that through.

- Mike

<mhideo> okay, so my plan is to talk to the writers and translation to get their feedback on replacing the product and edition tags and see how that will effect them.
<mhideo> thank you again!
<jensp> ok cool - glad to be of assistance
<jensp> though maybe the current map:
<jensp> edition -> rpmversion
<jensp> pubsnum -> rpmrelease
<jensp> product version -> disttag
<mhideo> ahh yes, clever!
<jensp> is workable anyway I feel for rhel at least
<jensp> jboss might be harder, dunno

I sort of missed these comments at the time.

(In reply to comment #63)
> "Another option is to look at a streamlined set of review items for
> publican-created doc packages... We've never explicitly done this but in
> practice, people know they don't have to check, for instance, shared
> library guidelines when writing and reviewing a pure python module."
> 
> Someone would first need to propose what the specific set of review items for
> publican-created doc packages should be. The way to do this is to create a wiki
> page under: https://fedoraproject.org/wiki/PackagingDrafts/

I agree with this idea: it would be good to have an explicit Packaging Guideline for publican documentation.  Basically it all rests on publican since it can generate srpm packages directly from SCM and should be capable of submitting packages directly to koji from svn (like it does for brew inside Red Hat), so in that sense this is nothing to review once publican's templates have been approved as good for Fedora.  The general view seems to be that documentation writers and translators in particular should not have to do all the cvs jigs to get books built in the buildsystem so I think yes some special provisions are needed for publican publishing to Fedora.  (Other options would include a special writer packager category say in FAS/koji or even a separate repo for documentation publishing (eg dist-f12-docs?).)

I reworked my patch to preserve the name of all the current rpms (src and noarch):

Please test:
http://petersen.fedorapeople.org/publican/publican-0.45-0.4+naming.fc11.noarch.rpm

This package should have brew-* and web-* targets continuing to work unchanged as before (only changes to the .spec and tarball names), and provide new make targets fedora-* and koji-* for creating fedora rpms and pushing builds to koji.

Eric, Mike, Josh, Ryan, Rueddi, et al: can you please test the package in comment 74 to make sure it works for you so we can move forward with getting the fedora publican upstream into publican, thanks!  It should be a drop in replacement for current publican-0.45 just with added fedora support.

http://petersen.fedorapeople.org/publican/publican-0.45-0.7+fedora.fc10.noarch.rpm

This one I actually tested with a scratch build in brew (see the publican bug).
So I am confident now that the patch should be ok with the current redhat workflow.

Here is a koji scratch build done with it too:
http://koji.fedoraproject.org/koji/taskinfo?taskID=1369750

SPEC:http://sparks.fedorapeople.org/Packages/security-guide/fedora-security-guide-en-US.spec

SRPM: http://sparks.fedorapeople.org/Packages/security-guide/fedora-security-guide-en-US-1.0-14.fc11.src.rpm

RPMLINT:
[christensene@localhost rpm]$ rpmlint SRPMS/fedora-security-guide-en-US-1.0-14.fc11.src.rpm 
1 packages and 0 specfiles checked; 0 errors, 0 warnings.
[christensene@localhost rpm]$ rpmlint SPECS/fedora-security-guide-en-US.spec 
0 packages and 1 specfiles checked; 0 errors, 0 warnings.

Thanks, Eric:
http://koji.fedoraproject.org/koji/taskinfo?taskID=1416026


Mike, any idea when we might be able to apply the publican patch to fedora?

Jens,
Where are we now on this?

I can approve the package (no problem technically there)
but I would really like to hear an official word from Fedora Docs
saying they are happy to import packages to Fedora with
a forked version of publican until (if?) my patch gets included.
(Again I am more than happy to build the patched publican
in fedora if someone can give me a green light for that.)

BTW where can one get the publican-1.0 test code?
And who is going to build it for F12?

Approved to use a "hacked" version of Publican as long as it isn't changing the building which would having problems in koji, too. (which this one isn't).

https://fedoraproject.org/wiki/Meeting:Docs_IRC_log_20090709

Okay.

Package is APPROVED for inclusion in Fedora by Jens Petersen.


I will still feel more comfortable once the publican patch goes
into rawhide: do hope that will happen very soon.
Since it has been tested and there are no known problems with
it I don't seen any reason not to go ahead with that.
In the meantime I will try to update the package to be based
off the fedora publican.spec since svn is out of sync.

New Package CVS Request
=======================
Package Name: fedora-security-guide
Short Description: A Guide to Securing Fedora Linux
Owners: sparks radsy
Branches: F-10 F-11
InitialCC: mhideo

CVS done.

(In reply to comment #84)
> CVS done.  

Sorry...  I forgot about this being a Publican doc...

The package name is actually fedora-security-guide-en-US.  Can that be changed, please?

(In reply to comment #85)
> (In reply to comment #84)
> > CVS done.  
> 
> Sorry...  I forgot about this being a Publican doc...
> 
> The package name is actually fedora-security-guide-en-US.  Can that be changed,
> please?  

Disregard...

New Package CVS Request
=======================
Package Name: fedora-security-guide-en-US
Short Description: A Guide to Securing Fedora Linux
Owners: sparks radsy
Branches: F-10 F-11
InitialCC: mhideo  

The previous CVS name was in error.  Sorry, my mistake.

abadger1999 fixed this for me.

Seems the wrong srpm was imported to cvs.

Why not the approved package from comment 77?

fedora-security-guide-en-US-1.0-17.fc11 has been submitted as an update for Fedora 11.
http://admin.fedoraproject.org/updates/fedora-security-guide-en-US-1.0-17.fc11

fedora-security-guide-en-US-1.0-17.fc10 has been submitted as an update for Fedora 10.
http://admin.fedoraproject.org/updates/fedora-security-guide-en-US-1.0-17.fc10

Turns out Eric updated the source I guess and then used
the wrong publican make target to generate the imported
package I guess.

Please use "make fedora-srpm-en-US" for this package.

fedora-security-guide-en-US-1.0-17.fc10 has been pushed to the Fedora 10 testing repository.  If problems still persist, please make note of it in this bug report.
 If you want to test the update, you can install it with 
 su -c 'yum --enablerepo=updates-testing update fedora-security-guide-en-US'.  You can provide feedback for this update here: http://admin.fedoraproject.org/updates/F10/FEDORA-2009-8064

fedora-security-guide-en-US-1.0-17.fc11 has been pushed to the Fedora 11 testing repository.  If problems still persist, please make note of it in this bug report.
 If you want to test the update, you can install it with 
 su -c 'yum --enablerepo=updates-testing update fedora-security-guide-en-US'.  You can provide feedback for this update here: http://admin.fedoraproject.org/updates/F11/FEDORA-2009-8071

fedora-security-guide-en-US-1.0-17.fc10 has been pushed to the Fedora 10 stable repository.  If problems still persist, please make note of it in this bug report.

fedora-security-guide-en-US-1.0-17.fc11 has been pushed to the Fedora 11 stable repository.  If problems still persist, please make note of it in this bug report.