Bug 170522

Created attachment 119842 [details]
docs-common.patch

LOOKSGOODTOME

Caveat:  I don't read Makefileze very well, so I'm not giving this a technical
pass.  The concepts, OTOH, I do highly approve of.

Tommy's opinion is the next?  And Paul's?

Hmm, some of this looks good, other parts not so much... First, the good:

1. I like the idea (and execution) of the targets "local-{archive|rpm}" vs.
"{archive|rpm}".
2. The various Red Hat-ism changes such as renaming to .spec.in, and explicitly
giving the file names, are cool with me, good ideas.  I confess to taking
shortcuts while putting this stuff together out of laziness. :-)

Things I'm not so keen on:

1. First and foremost, building from your Makefile fails for me due to temp
files in my local dir.  The "find | xargs | find" I did in the original Makefile
was designed to stop that sort of nonsense.  If we could fix that with better
"-X" tar magic, that would be fine too.
2. Building depends on the user having a writable rpmbuild tree outside the docs
area.  I did this the (saner, IMHO) way that Fedora Extras does it, where
nothing is assumed and a local rpmbuild tree is used instead.  Thus the RPMFLAGS.
3. What happened to the .menu file?  Required for other doc packages.
4. Where is the %changelog?  Now rpmlint barfs on the package.
5. The .eps files are large and (currently?) useless in the context of this
package, so I would vote for excluding them from the install.  Similarly, the
.svg files are not much use but would make sense in the .src.rpm package if we
even want one.

I'm not a Makefile expert either, so if I've missed some logic here, clues are
welcome!

1) Don't build using temporary files in "/tmp" unless you add uniqueness to
avoid collisions.  Easier to use a "tmp-$$" subdir in the $PWD.

2) Take out all the rules from "Makefile" and friends.  Add generic "rpm:" and
"local-rpm" targets into the "docs-common/Makefile.common" file and invoke a
helper script that does all the dirty work.

I can help with this once the dust settles on what you folk want to do...

> 1. First and foremost, building from your Makefile fails for me due to temp
> files in my local dir.  The "find | xargs | find" I did in the original Makefile
> was designed to stop that sort of nonsense.  If we could fix that with better
> "-X" tar magic, that would be fine too.
Could you please send me the failure for building in /tmp.  It worked fine for
me of course, but I'm curious where it breaks down for you.  The use of storing
the buildroot in /tmp is fairly common in other RH spec files.  If you would
like we can change that to $(mktemp /tmp/fdp-XXXXXX).

> 2. Building depends on the user having a writable rpmbuild tree outside the docs
> area.  I did this the (saner, IMHO) way that Fedora Extras does it, where
> nothing is assumed and a local rpmbuild tree is used instead.  Thus the RPMFLAGS.

That is the case for non-root building rpms in all cases.  We can build in some
custom stuff to allow non-root rpmbuild's.  But many times those approaches
interferre with users who have $HOME/.rpmmacros.  Just can't win here, good
enough to make the pieces available and let them go from there.

> 3. What happened to the .menu file?  Required for other doc packages.
Any changes to %files in the .spec.in should not be difficult

> 4. Where is the %changelog?  Now rpmlint barfs on the package.
Changelogs should be maintained manually, not autogenerated.

> 5. The .eps files are large and (currently?) useless in the context of this
> package, so I would vote for excluding them from the install.  Similarly, the
> .svg files are not much use but would make sense in the .src.rpm package if we
> even want one.
Same thing I think, just a change to the %files to {in,ex}clude what you want

Many thanks.

The temporary files interfering with the build weren't in /tmp, they were
.#something-or-other in the local doc directory.  (Backups of stuff overwritten
during a CVS operation, IOW.)  The point I was making is that we should probably
declare exactly what needs to go into the tarball rather than using a blanket
"cp -someopts * <somewhere>", especially in cahoots with a "make install" that
does an "install *" or "cp *".  I think you're agreeing with me, given your
comments on issue 5, so that's cool.

As for non-root builds of RPMs, using flags for RPM such as --define "_topdir
$(PWD)" would be a good idea.  Refer to my original Makefile stuff for examples.
 I do all my work as non-root user, of course, and although I have a ~/rpmbuild
tree built with fedora-buildrpmtree (like most FE packagers/developers), I don't
think we should assume all doc builders will do likewise.  In fact, not even FE
standards require ~/rpmbuild; as I mentioned, they do building within the user's
CVS checkout, again using --define options for rpmbuild.

The way FE is doing this is pretty good IMHO; they make very few assumptions
about the user environment so a lot of things work that might otherwise break
given the multiplicity of setups, especially among the "power developers/users"
who work on FE.  I'm inclined to follow that lead.

As for %changelog -- how do you propose we handle this, since the building is
done automatically?  Keep in mind that there is currently a single .spec.in for
the common stuff, but what about the .spec.in that serves all other documents? 
I can see getting that out of CVS with some sort of magic perhaps; but for
multi-file documents with a parent and subordinate XML files, which CVS log to
use?  And how the heck to do it cleanly?  I'm CCing Tommy for guidance since he
may have had to deal with this sort of thing before.

(In reply to comment #6)
> The temporary files interfering with the build weren't in /tmp, they were
> .#something-or-other in the local doc directory.  (Backups of stuff overwritten
> during a CVS operation, IOW.)  The point I was making is that we should probably
> declare exactly what needs to go into the tarball rather than using a blanket
> "cp -someopts * <somewhere>", especially in cahoots with a "make install" that
> does an "install *" or "cp *".  I think you're agreeing with me, given your
> comments on issue 5
>               , so that's cool.

Excellent point about the "install:" rule.  I just discovered this while making
changes and my vim .swp files were pulled into the archive.  Perhaps not a bad
idea to be explicit in the rule.

 
> As for non-root builds of RPMs, using flags for RPM such as --define "_topdir
> $(PWD)" would be a good idea.  Refer to my original Makefile stuff for examples.
>  I do all my work as non-root user, of course, and although I have a ~/rpmbuild
> tree built with fedora-buildrpmtree (like most FE packagers/developers), I don't
> think we should assume all doc builders will do likewise.  In fact, not even FE
> standards require ~/rpmbuild; as I mentioned, they do building within the user's
> CVS checkout, again using --define options for rpmbuild.

I'm not sure I like this approach, mainly because it was interferring with my
.rpmmacros customizations.  Also, using the --defines is only one of several
methods to provide non-root package builds.  I would argue for the case of
creating the src.rpm as we do, and let the user/admin determine the best method
to proceed.  We can document several acceptable methods for those who aren't
sure how to proceed.  I used to construct an rpm devel environment in my
Makefiles ($dir/{RPM,SPEC,SOURCE,BUILD,TMP}), but found that it broke for the
setup used by others internally.  So now I just do enough to lay down the bits
acceptable to the build system (the src.rpm).  Thoughts?


> The way FE is doing this is pretty good IMHO; they make very few assumptions
> about the user environment so a lot of things work that might otherwise break
> given the multiplicity of setups, especially among the "power developers/users"
> who work on FE.  I'm inclined to follow that lead.

> As for %changelog -- how do you propose we handle this, since the building is
> done automatically?  Keep in mind that there is currently a single .spec.in for
> the common stuff, but what about the .spec.in that serves all other documents? 
> I can see getting that out of CVS with some sort of magic perhaps; but for
> multi-file documents with a parent and subordinate XML files, which CVS log to
> use?  And how the heck to do it cleanly?  I'm CCing Tommy for guidance since he
> may have had to deal with this sort of thing before.

For the main fedora-doc-common.rpm I would suggest creating a
docs-common/ChangeLog (that would be included as a %doc).  This would tend to be
a detailed account of the fedora-doc-common changes.  Then,
packaging/fedora-doc-common.spec.in would have a %changelog that reflects a
higher-level of changes, and those geared towards packaging.

Hrmm, now what about the documents themselves.  I didn't like the autogenerated
approach as it didn't reflect real life (what the auther actually was doing).  I
would propose the same "ChangeLog".  I've tried doing things in the past where I
would grab the cvs log for the packages, but that was ugly and pulled in a ton
of minor changes (spacing,formatting) and was difficult to sort when lots of
.xml files were involved.  Perhaps just letting the author specific their
changes in the form of a ChangeLog file is flexible enough for them to use or
not use.  We could also do some magic in the form of scrapping <revhistory>
contents, but that also seems a bit ugly.  

I sort of enjoy the some-other-doc/ChangeLog approach because it allows the
authers to document major milestone changes in their document in plain english.
 Also it acts as a opt-in or opt-out ... meaning they can skip it if they don't
want to be involved in it (we'll just create a empty stub %changelog in that
case).  Thoughts?

Sorry for the long delay on this bug.  I'm uncertain where we are on this topic,
but I think we have some of the document-specific things happening in
rpm-info.xml now.  That file is very much an opt-in kind of record, which seems
to satisfy some of what I see desired here, but doesn't induce the docs
maintainers to engage in keeping up Yet Another Supporting File.  The %changelog
sections in the spec files are to be used in a more packaging-specific way, as
done Fedora-wide, rather than restating what goes in rpm-info.  I still like the
idea of a fedora-doc-common ChangeLog file, packaged as a %doc, since it
obviously has no analogous rpm-info.xml file.

It looks like our SRPM files will probably be entered into the greater package
universe, and let each build system (including local users/admins) deal with it
as desired, rather than dictating an RPM building scheme here.  (The mock
strategy would kind of make any such scheme superfluous anyway.)

Many of these steps have been taken in the release-notes module already, which
is the model I intend to follow for now.  I'd encourage a looksee at our latest
iteration by anyone still interested.  The release-notes module is a little odd
since it relies on a group of tarballs created by many different modules, but
hopefully it gives a suitable appearance.

This bug is probably not the place to have further very detailed discussions --
I'd rather have them on fedora-docs-list where it's easier for all the
contributors to read, understand, and offer opinions.  I'll close this bug as
RAWHIDE for now and we can take up extra conversations on the list.

Ticket moved to allow products to be removed from BZ.