Let me preface this by mentioning that I haven't got a clue about packaging, so assuming I am a complete idiot wouldn't be inappropriate.
Eric discovered back in January that there are a couple of show stoppers to using Publican for Docs. He thought he was going to get the issues fixed in a short time, but that hasn't happened, and it doesn't look like it will happen. Eric developed a workaround by hacking Publican. Unfortunately, using this approach would require everyone participating in Docs to have a hacked Publican, and the hack breaks Publican for other uses. A switch would be nice, and acceptable to the Publican developers, but apparently it would take a lot of effort and there is only one maintainer.
Publican does almost everything we need to do between the wiki and the RPM, so we would really like to use it rather than the mish-mash of tools we currently have.
There are two problems: 1) Publican names the package incorrectly 2) The .desktop file is handled differently than the reviewers would like
Now it seems to me, worst case we could run Publican and then package the HTMLs manually. But since Publican already does most of the heavy lifting, why not simply patch Publican's work after the fact.
To this end, I made an attempt to do the following: 1) Unpack the SRPM produced by Publican, The SRPM has 2 files, a tarball and a specfile 2) Rename the tarball, which involves untarring and retarring it 3) Edit the specfile 4) rpmbuild
I wrote down the details of what I did at https://fedoraproject.org/wiki/User:Jjmcd/Drafts/Converting_Publican_RPM_for...
When I do this, the resulting RPM passes rpmlint, installs correctly, and seems to meet the guidelines. What am I missing? Well, appears to install correctly. A menu entry appears and when I click on it I see release notes. Maybe there are less obvious things going on.
As far as the .desktop file, I don't fully understand the issue here. The code produced by Publican appears to be almost identical to that in the packaging guidelines on the wiki and very similar to what it is in the current release notes. David Nally tells me of an entirely different way to deal with the .desktop file but I don't know enough to understand why it is better.
So what I'm asking is: 1) Is this totally wrong-headed and we should be looking up another avenue 2) How can this approach be made better 3) Is there some other way
Thanks --McD
On Thu, Mar 12, 2009 at 08:57:52AM -0400, John J. McDonough wrote:
Let me preface this by mentioning that I haven't got a clue about packaging, so assuming I am a complete idiot wouldn't be inappropriate.
Eric discovered back in January that there are a couple of show stoppers to using Publican for Docs. He thought he was going to get the issues fixed in a short time, but that hasn't happened, and it doesn't look like it will happen. Eric developed a workaround by hacking Publican. Unfortunately, using this approach would require everyone participating in Docs to have a hacked Publican, and the hack breaks Publican for other uses. A switch would be nice, and acceptable to the Publican developers, but apparently it would take a lot of effort and there is only one maintainer.
Can Jeff Fearn or some other knowledgeable person explain here what's needed for that switch? We probably can find some resources for writing that switch, but to do that we need to know what's required.
Publican does almost everything we need to do between the wiki and the RPM, so we would really like to use it rather than the mish-mash of tools we currently have.
There are two problems:
- Publican names the package incorrectly
- The .desktop file is handled differently than the reviewers would like
Now it seems to me, worst case we could run Publican and then package the HTMLs manually. But since Publican already does most of the heavy lifting, why not simply patch Publican's work after the fact.
To this end, I made an attempt to do the following:
- Unpack the SRPM produced by Publican, The SRPM has 2 files, a tarball and
a specfile 2) Rename the tarball, which involves untarring and retarring it 3) Edit the specfile 4) rpmbuild
Publican also has a 'make tar-<LANG>' target for making just the tarball.
I wrote down the details of what I did at https://fedoraproject.org/wiki/User:Jjmcd/Drafts/Converting_Publican_RPM_for...
When I do this, the resulting RPM passes rpmlint, installs correctly, and seems to meet the guidelines. What am I missing? Well, appears to install correctly. A menu entry appears and when I click on it I see release notes. Maybe there are less obvious things going on.
As far as the .desktop file, I don't fully understand the issue here. The code produced by Publican appears to be almost identical to that in the packaging guidelines on the wiki and very similar to what it is in the current release notes. David Nally tells me of an entirely different way to deal with the .desktop file but I don't know enough to understand why it is better.
So what I'm asking is:
- Is this totally wrong-headed and we should be looking up another avenue
- How can this approach be made better
- Is there some other way
It might be helpful to have David or someone to describe the exact issue with the .desktop file here, or just point us to a bug where we can read about it. I'm looking at Publican to see whether we could add the needed stuff to /usr/share/publican/make/Makefile.fedora, which would keep it in the Fedora brand package and away from where it breaks other things that Red Hat might use internally.
If that ends up being a bad place to put things -- because the Makefile.templates haven't been included yet at that point, perhaps -- then it would seem relatively easy to also have the Makefile.common provide:
ifeq "$(BRAND_MAKE)" "1" include $(COMMON_CONFIG)/make/Makefile.$(BRAND).post endif
After the global templates, and we can craft those targets as needed. I'm not completely Makefile-ignorant, fortunately, after having spent some time working on our FDP toolchain. I'll try to help where I can. If Jeff's willing to take a patch like that, or if he can help me understand where's a better place to put these sorts of customizations, I'm up for writing them. We really do not want to have to punt this again for lack of elbow grease.
----- Original Message ----- From: "Paul W. Frields" stickster@gmail.com To: fedora-docs-list@redhat.com Sent: Thursday, March 12, 2009 10:19 AM Subject: Re: Publican Issues for RNs
Can Jeff Fearn or some other knowledgeable person explain
Unfortunately, I don't know all the players that well. A Jeff did come on to the phone call the other night, and I got the impression that he had something to do with Publican. Eric had indicated that making it a switch would require massive work, although the other night the possibility that it might not be all that bad was raised. There was even talk of putting it into the Fedora template but perhaps that was only wishful thinking.
Publican also has a 'make tar-<LANG>' target for making just the tarball.
Even make srpm leaves the tar laying around, but if it is already willing to have a shot at the spec file why not let it do that work too.
It might be helpful to have David or someone to describe the exact issue with the .desktop file here, or just point us to a bug
Clearly I don't understand this bit at all, and that has to be the next place to dig. Eric was the one who had his srpm refused, so perhaps if Eric, David and myself, or perhaps someone else knowledgable can get together we can sort it out.
I'm looking at Publican to see whether we could add the needed stuff to /usr/share/publican/make/Makefile.fedora
Eric knows exactly what has to happen inside Publican, he just didn't know how to make it optional.
I'm not completely Makefile-ignorant
I'm not either, but I'm hardly a maestro.
We really do not want to have to punt this again for lack of elbow grease.
I think even worst case it isn't too bad, but the smoother we can make it the better. Maybe that is selfish -- I want to have it easy next time ;-)
--McD
On Thu, Mar 12, 2009 at 02:36:08PM -0400, John J. McDonough wrote:
From: "Paul W. Frields" stickster@gmail.com
Can Jeff Fearn or some other knowledgeable person explain
Unfortunately, I don't know all the players that well. A Jeff did come on to the phone call the other night, and I got the impression that he had something to do with Publican. Eric had indicated that making it a switch would require massive work, although the other night the possibility that it might not be all that bad was raised. There was even talk of putting it into the Fedora template but perhaps that was only wishful thinking.
I'm almost certain that would have been Jeff Fearn, who's the Publican developer; he works at Red Hat in the Brisbane (BNE) office.
The more of that stuff we can get on the list, the more people we can potentially rope into helping. I tend to think that phone calls are great for small issues and status reports, but aren't good for bigger ones in terms of the openness and transparency we need for awesome teamwork.
Publican also has a 'make tar-<LANG>' target for making just the tarball.
Even make srpm leaves the tar laying around, but if it is already willing to have a shot at the spec file why not let it do that work too.
It might be helpful to have David or someone to describe the exact issue with the .desktop file here, or just point us to a bug
Clearly I don't understand this bit at all, and that has to be the next place to dig. Eric was the one who had his srpm refused, so perhaps if Eric, David and myself, or perhaps someone else knowledgable can get together we can sort it out.
Right on, and please relay the findings here if you can.
I'm looking at Publican to see whether we could add the needed stuff to /usr/share/publican/make/Makefile.fedora
Eric knows exactly what has to happen inside Publican, he just didn't know how to make it optional.
I'm almost certain that I can make another set of templates and provide an appropriate specfile template that would DTRT, as long as I understand what the issues are. Then it's just a matter of finding out whether Jeff will take the patch. My preference would be to find a solution that can be contained entirely in the publican-fedora package, thus minimizing any effect on the rest of the Publican package.
I'm not completely Makefile-ignorant
I'm not either, but I'm hardly a maestro.
Between the two of us we could probably be a genius! :-)
We really do not want to have to punt this again for lack of elbow grease.
I think even worst case it isn't too bad, but the smoother we can make it the better. Maybe that is selfish -- I want to have it easy next time ;-)
I want to have it easy *this* time because last time we said the same thing! :-)
----- Original Message ----- From: "Paul W. Frields" stickster@gmail.com To: fedora-docs-list@redhat.com Sent: Thursday, March 12, 2009 7:10 PM Subject: Re: Publican Issues for RNs
The more of that stuff we can get on the list, the more people we can potentially rope into helping. I tend to think that phone calls are great for small issues and status reports, but aren't good for bigger ones in terms of the openness and transparency we need for awesome teamwork.
I agree and I'm surprised that nobody else has joined in this coversation. OTOH, the phone conversation did get a lot of turf covered quickly, at the expense of limited participation and no record to go back and study.
It might be helpful to have David or someone to describe the exact issue with the .desktop file here, or just point us to a bug
mhideo just appeared on IRC asking about bug 476471 which seems to be the one Eric was talking about. There are a LOT of comments almost every one of which has a link. This will take more than a minute or two to digest.
--McD
Paul W. Frields wrote:
On Thu, Mar 12, 2009 at 08:57:52AM -0400, John J. McDonough wrote:
Let me preface this by mentioning that I haven't got a clue about packaging, so assuming I am a complete idiot wouldn't be inappropriate.
Eric discovered back in January that there are a couple of show stoppers to using Publican for Docs. He thought he was going to get the issues fixed in a short time, but that hasn't happened, and it doesn't look like it will happen. Eric developed a workaround by hacking Publican. Unfortunately, using this approach would require everyone participating in Docs to have a hacked Publican, and the hack breaks Publican for other uses. A switch would be nice, and acceptable to the Publican developers, but apparently it would take a lot of effort and there is only one maintainer.
Can Jeff Fearn or some other knowledgeable person explain here what's needed for that switch? We probably can find some resources for writing that switch, but to do that we need to know what's required.
I haven't looked to deeply in to it. The tar/package name structure is use in many of the templates in the common Makefiles and testing having two naming methods would require some pretty robust analysis.
Publican does almost everything we need to do between the wiki and the RPM, so we would really like to use it rather than the mish-mash of tools we currently have.
There are two problems:
- Publican names the package incorrectly
For values of incorrectly that are not in the published fedora package naming guidelines AND for values of incorrectly that fail miserably to understand the value-add that having access to multiple versions of product documentation on your desktop offers.
Being able to review the fedora 11 release notes on fedora 10 while you are off line is a valuable feature.
Having access to the admin guides for multiple versions of fedora on your desktop is a valuable feature, particularly if you have to support multiple versions of fedora. Like say a system administrator.
It only takes a little imagination to see how this benefits being able to syndicate content to the desktop. I'm surprised the fedora docs team aren't screaming for this feature.
- The .desktop file is handled differently than the reviewers would like
For values of like that ignore compatibility with other distros.
Now it seems to me, worst case we could run Publican and then package the HTMLs manually. But since Publican already does most of the heavy lifting, why not simply patch Publican's work after the fact.
To this end, I made an attempt to do the following:
- Unpack the SRPM produced by Publican, The SRPM has 2 files, a tarball and
a specfile 2) Rename the tarball, which involves untarring and retarring it 3) Edit the specfile 4) rpmbuild
Publican also has a 'make tar-<LANG>' target for making just the tarball.
If you run make spec-<LANG> it will make the spec and the tar.
BTW fedora packaging requires you to check TAR files in to CVS to get them built in koji, the srpm is just used for package review, after that you have to check the spec and tar file in to CVS, tag it and build it in koji. Much of the benefit of getting a source rpm is lost at that point. If you can't get a number in a package name I seriously doubt you will be allowed to push source rpms in to koji.
I wrote down the details of what I did at https://fedoraproject.org/wiki/User:Jjmcd/Drafts/Converting_Publican_RPM_for...
I thought this was pretty neat, but it's probably easier just to run make spec and use the sources in tmp/rpm.
When I do this, the resulting RPM passes rpmlint, installs correctly, and seems to meet the guidelines. What am I missing? Well, appears to install correctly. A menu entry appears and when I click on it I see release notes. Maybe there are less obvious things going on.
As far as the .desktop file, I don't fully understand the issue here. The code produced by Publican appears to be almost identical to that in the packaging guidelines on the wiki and very similar to what it is in the current release notes. David Nally tells me of an entirely different way to deal with the .desktop file but I don't know enough to understand why it is better.
So what I'm asking is:
- Is this totally wrong-headed and we should be looking up another avenue
- How can this approach be made better
- Is there some other way
It might be helpful to have David or someone to describe the exact issue with the .desktop file here, or just point us to a bug where we can read about it. I'm looking at Publican to see whether we could add the needed stuff to /usr/share/publican/make/Makefile.fedora, which would keep it in the Fedora brand package and away from where it breaks other things that Red Hat might use internally.
It would mean other brands being used on fedora wouldn't be usable for fedora packages.
If that ends up being a bad place to put things -- because the Makefile.templates haven't been included yet at that point, perhaps -- then it would seem relatively easy to also have the Makefile.common provide:
ifeq "$(BRAND_MAKE)" "1" include $(COMMON_CONFIG)/make/Makefile.$(BRAND).post endif
After the global templates, and we can craft those targets as needed. I'm not completely Makefile-ignorant, fortunately, after having spent some time working on our FDP toolchain. I'll try to help where I can. If Jeff's willing to take a patch like that, or if he can help me understand where's a better place to put these sorts of customizations, I'm up for writing them. We really do not want to have to punt this again for lack of elbow grease.
We use the double colon for targets, e.g. foo::, so you can't over ride them, you can only add pre/post processing to them. You could add new targets that depend on old targets or just cut, paste and rename existing templates, then change the behaviour.
Really though, by doing this you are removing what is, IMHO, the biggest value-add of packaging the docs in the first place, the ability to have a library of content at your fingertips. Huge price to pay just to get rid of a number.
Cheers, Jeff.
On Fri, Mar 13, 2009 at 04:49:42PM +1000, Jeff Fearn wrote:
Paul W. Frields wrote:
On Thu, Mar 12, 2009 at 08:57:52AM -0400, John J. McDonough wrote:
Let me preface this by mentioning that I haven't got a clue about packaging, so assuming I am a complete idiot wouldn't be inappropriate.
Eric discovered back in January that there are a couple of show stoppers to using Publican for Docs. He thought he was going to get the issues fixed in a short time, but that hasn't happened, and it doesn't look like it will happen. Eric developed a workaround by hacking Publican. Unfortunately, using this approach would require everyone participating in Docs to have a hacked Publican, and the hack breaks Publican for other uses. A switch would be nice, and acceptable to the Publican developers, but apparently it would take a lot of effort and there is only one maintainer.
Can Jeff Fearn or some other knowledgeable person explain here what's needed for that switch? We probably can find some resources for writing that switch, but to do that we need to know what's required.
I haven't looked to deeply in to it. The tar/package name structure is use in many of the templates in the common Makefiles and testing having two naming methods would require some pretty robust analysis.
Publican does almost everything we need to do between the wiki and the RPM, so we would really like to use it rather than the mish-mash of tools we currently have.
There are two problems:
- Publican names the package incorrectly
For values of incorrectly that are not in the published fedora package naming guidelines AND for values of incorrectly that fail miserably to understand the value-add that having access to multiple versions of product documentation on your desktop offers.
Being able to review the fedora 11 release notes on fedora 10 while you are off line is a valuable feature.
Having access to the admin guides for multiple versions of fedora on your desktop is a valuable feature, particularly if you have to support multiple versions of fedora. Like say a system administrator.
It only takes a little imagination to see how this benefits being able to syndicate content to the desktop. I'm surprised the fedora docs team aren't screaming for this feature.
Re: https://bugzilla.redhat.com/show_bug.cgi?id=476471 , I assume.
Don't we have version names in other packages, such as in the case of compatibility libraries? Like libsoup22, for instance? It seems to me there's a precedent for this. Added my comment to the bug FWIW.
- The .desktop file is handled differently than the reviewers would like
For values of like that ignore compatibility with other distros.
We could simply provide a patch or separate .desktop file, I suppose. Typically no independent, cross-distro upstream would take a patch that breaks other distros in favor of Fedora. At the same time, Fedora standards are against carrying long-term patches, in favor of working with upstream. If that's an unresolvable conflict, might be a matter to take to the Packaging committee, if nothing else asking for them to write an exception into the policy.
Now it seems to me, worst case we could run Publican and then package the HTMLs manually. But since Publican already does most of the heavy lifting, why not simply patch Publican's work after the fact.
To this end, I made an attempt to do the following:
- Unpack the SRPM produced by Publican, The SRPM has 2 files, a tarball and
a specfile 2) Rename the tarball, which involves untarring and retarring it 3) Edit the specfile 4) rpmbuild
Publican also has a 'make tar-<LANG>' target for making just the tarball.
If you run make spec-<LANG> it will make the spec and the tar.
BTW fedora packaging requires you to check TAR files in to CVS to get them built in koji, the srpm is just used for package review, after that you have to check the spec and tar file in to CVS, tag it and build it in koji. Much of the benefit of getting a source rpm is lost at that point. If you can't get a number in a package name I seriously doubt you will be allowed to push source rpms in to koji.
Right, but you can do a "cvs-import.sh <SRPM>" to do this, which I have done repeatedly for previous fedora-release-notes packages. However, if the built-in .spec or some contents of the .tar aren't already in the form you want them, that's not going to be advantageous.
I wrote down the details of what I did at https://fedoraproject.org/wiki/User:Jjmcd/Drafts/Converting_Publican_RPM_for...
I thought this was pretty neat, but it's probably easier just to run make spec and use the sources in tmp/rpm.
When I do this, the resulting RPM passes rpmlint, installs correctly, and seems to meet the guidelines. What am I missing? Well, appears to install correctly. A menu entry appears and when I click on it I see release notes. Maybe there are less obvious things going on.
As far as the .desktop file, I don't fully understand the issue here. The code produced by Publican appears to be almost identical to that in the packaging guidelines on the wiki and very similar to what it is in the current release notes. David Nally tells me of an entirely different way to deal with the .desktop file but I don't know enough to understand why it is better.
So what I'm asking is:
- Is this totally wrong-headed and we should be looking up another avenue
- How can this approach be made better
- Is there some other way
It might be helpful to have David or someone to describe the exact issue with the .desktop file here, or just point us to a bug where we can read about it. I'm looking at Publican to see whether we could add the needed stuff to /usr/share/publican/make/Makefile.fedora, which would keep it in the Fedora brand package and away from where it breaks other things that Red Hat might use internally.
It would mean other brands being used on fedora wouldn't be usable for fedora packages.
I see your point.
If that ends up being a bad place to put things -- because the Makefile.templates haven't been included yet at that point, perhaps -- then it would seem relatively easy to also have the Makefile.common provide:
ifeq "$(BRAND_MAKE)" "1" include $(COMMON_CONFIG)/make/Makefile.$(BRAND).post endif
After the global templates, and we can craft those targets as needed. I'm not completely Makefile-ignorant, fortunately, after having spent some time working on our FDP toolchain. I'll try to help where I can. If Jeff's willing to take a patch like that, or if he can help me understand where's a better place to put these sorts of customizations, I'm up for writing them. We really do not want to have to punt this again for lack of elbow grease.
We use the double colon for targets, e.g. foo::, so you can't over ride them, you can only add pre/post processing to them. You could add new targets that depend on old targets or just cut, paste and rename existing templates, then change the behaviour.
Really though, by doing this you are removing what is, IMHO, the biggest value-add of packaging the docs in the first place, the ability to have a library of content at your fingertips. Huge price to pay just to get rid of a number.
Yeah, that's clearer to me now.
John J. McDonough wrote:
There are two problems:
- Publican names the package incorrectly
Can you clearly define what the problem is here? Please provide links to emails or documents which support where the misnaming is occurring. As a maintainer of one of the publican sub-packages I would really like to know what is wrong with it so I can work towards a solution.
- The .desktop file is handled differently than the reviewers would like
Same here. Can you provide links to the archived emails from these reviewers so I can assist in creating a solution to this.
On Thu, Mar 12, 2009 at 8:57 AM, John J. McDonough wb8rcr@arrl.net wrote:
As far as the .desktop file, I don't fully understand the issue here. The code produced by Publican appears to be almost identical to that in the packaging guidelines on the wiki and very similar to what it is in the current release notes. David Nally tells me of an entirely different way to deal with the .desktop file but I don't know enough to understand why it is better.
So the spec file you guys have creates a .desktop file, but doesn't do so in the way the packaging guidelines require that it must be done.
https://fedoraproject.org/wiki/Packaging/Guidelines#desktop-file-install_usa...
So, I had the same problem with my first desktop package and read the section immediately preceeding the above section and tried to create it by hand.
From that section: (and emphasis is in the packaging guidelines, I
didn't add it): It is not simply enough to just include the .desktop file in the package, one MUST run desktop-file-install OR desktop-file-validate in %install (and have BuildRequires: desktop-file-utils), to help ensure .desktop file safety and spec-compliance. desktop-file-install MUST be used if the package does not install the file or there are changes desired to the .desktop file (such as add/removing categories, etc).
On 03/13/2009 10:58 AM, David Nalley wrote:
From that section: (and emphasis is in the packaging guidelines, I
didn't add it): It is not simply enough to just include the .desktop file in the package, one MUST run desktop-file-install OR desktop-file-validate in %install (and have BuildRequires: desktop-file-utils), to help ensure .desktop file safety and spec-compliance. desktop-file-install MUST be used if the package does not install the file or there are changes desired to the .desktop file (such as add/removing categories, etc).
These are real bugs, if you open a separate BZ I will fix these issues in a timely manner.
The complaint in the original bug is that the .desktop file is embedded in the spec file and is created when the binary rpms are built in Koji. They want the desktop file created when the srpm is created. Doing so breaks the desktop file for other rpm based distros, like Suse, who use different documentation paths. Embedding the desktop file in the spec means that at compile time we can source docdir from the build system creating proper desktop files for the system it is being built on.
While I can understand that distros may not care if other distros break or have to do extra work to get a proper desktop file, publican wants to work on these other distros, so the extra work will have to be done by the distro requesting the breaking change.
Cheers, Jeff.
-
Chris Curran -
David Nalley -
Jeff Fearn -
John J. McDonough -
Paul W. Frields