Publican Documentation Naming

Tue Mar 31 22:07:39 UTC 2009

On Tue, Mar 31, 2009 at 04:57:53PM -0400, Eric Christensen wrote:
> On Tue, 2009-03-31 at 16:54 -0400, Paul W. Frields wrote:
> > On Tue, Mar 31, 2009 at 02:20:32PM -0400, Eric Christensen wrote:
> > > Earlier today the Fedora Packaging Committee (FPC) looked at two
> > > "obstacles" to Publican-generated documentation.  The first was the
> > > naming convention[1] and the second was how Publican handles
> > > the .desktop in the SPEC file[2].  Both passed the FPC.
> > > 
> > > The FPC did say that we (the Docs Project) need to create a review
> > > process to ask "is this documentation really version specific? is there
> > > value in having multiple releases in the same dist at once?".  This is
> > > an important test that we need to develop and handle in-house.  This is
> > > NOT a solution to allow all Publican documents but it is a solution for
> > > allowing release-specific documents in Fedora.
> > > 
> > > Also discussed was the multiple SRPMs that are generated by having
> > > multiple languages for each document.  To simplify the process of
> > > reviewing these it was suggested that we use subpackaging.  Each SRPM
> > > for each language would be wrapped into a single package.
> > 
> > Allow me to play Devil's Advocate for a moment -- one of the reasons
> > for splitting out SRPMs per language, AIUI, is that it allows fixed
> > translations to be issued quickly without having to rebuild the entire
> > gamut of all languages for a document.  In other words, if someone
> > fixes the Security Guide's German (de) translation, you can simply
> > issue a new release of that package, and only people with the Security
> > Guide installed in German will get the update.
> > 
> > As far as I know, you can't tell our build systems to only
> > release one subpackage, and hold back all the others.  So if you want
> > to issue an update, you would be forced to issue all languages at
> > once, and you push an update on everyone, even people whose content is
> > not changing at all.
> > 
> > Just my limited understanding, there may be good arguments on both
> > sides of course.
> 
> Paul,
> I posed a similar question...  I'm pasting the conversation:
> 
> Sparks_Too> spot: I foresee a problem coming down the road.  Each
> language is packaged independently.  So that's going to mean a lot of
> packages hitting the review process within a short amount of time.
> <ke4qqq> yeah I was about to bring that up as well.
> <spot> Sparks_Too: each language is packaged independently?
> <spot> seriously? that's just broken.
> <Sparks_Too> spot: Yes
> <ke4qqq> another tool issue
> * tatica has quit (Read error: 110 (Connection timed out))
> <tibbs> Oh, please no.
> <spot> yeah, i'm not going to let that slide.
> <Sparks_Too> spot: In RH the reasoning is so there aren't 200MB docs...
> <ke4qqq> I suspect it's a plot to dramatically increase fedora package
> count :)
> <Sparks_Too> being downloaded for just one language.
> <spot> learn about subpackages.
> <Sparks_Too> So you would be able to install a language versus a
> document.
> <Sparks_Too> If that makes sense.
> <abadger1999> subpackage ++
> <ke4qqq> right, single srpm, 35 rpms
> <Sparks_Too> ke4qqq: This is a RH thing and not a Fedora thing.
> <spot> subpackages should be fine
> <spot> 35 base packages would not be
> <Sparks_Too> spot: Okay, not familiar but would be.
> <Sparks_Too> s/would/will
> <spot> Sparks_Too: basically, think of how the openssl package generates
> openssl and openssl-devel
> <spot> it is just one package for review (openssl)
> <spot> HowToFooAndBar could generate HTFAB-en and HTFAB-de
> <Sparks_Too> spot: Okay... so would we need ALL the languages in the
> package before it is approved?
> <tibbs> No.  You can just add a language once the package is in.
> <spot> Sparks_Too: nope. you can add subpackages as they are done.
> <spot> FPC, we're almost out of time
> <Sparks_Too> spot: Okay.  That works for me.  Our meeting is tomorrow so
> I'll bring it up then.  I don't have a problem with any of this, just
> need to learn more.
> 
> So when he said that not all the translations have to be in the package
> it sounded to me as if they weren't language specific and we wouldn't
> run into that problem.

I think we're talking apples and oranges here.  Let me see if I can
clarify.  This might be pedantic for people who already do packaging
(and if there are errors, of course you should blame me!).

In most cases in Fedora, subpackages make good sense.  If you are
packaging "libfoo," a library that provides a capability for "foo,"
you generally have one libfoo SRPM that generates several other
packages -- libfoo and libfoo-devel, for example.  (There might also
be an automatically generated libfoo-debuginfo, but let's leave that
aside for now.)

When you change something in the libfoo package to fix a bug, bumping
the release from libfoo-1.0-1 to libfoo-1.0-2, it makes very good
sense to push new libfoo and libfoo-devel packages at one time.  The
possibility that things *might* change from libfoo-1.0-1 to
libfoo-1.0-2 make it a good practice to simply always act as if they
*have* changed when issuing new packages.  When you issue a new
libfoo-1.0-2, you'll always push out a new libfoo-devel-1.0-2 as well.

Now, that works fine for documentation too, in *that* case -- in other
words, if you make some changes to the basic Security Guide, you would
of course want to push out the newest Guide in all languages.  But
here's where the subpackage use breaks down: You never see packagers
issuing a new libfoo-devel package without libfoo changing.  And that
can *definitely* happen in documentation.

For example, you could add a new, previously unused translation to
your Guide.  Using subpackaging, in order to issue it, you'd have to
rebuild the entire set of languages, and when you do, our build system
-- as far as I know -- won't let you just push the one new language
subpackage out.  It would require *all* the language subpackages to be
reissued, even if they hadn't changed at all.

Here's another twist that might make subpackages even more
unpalatable.  It implies that there will be a *resistance* to pushing
out translation fixes quickly.  There will be a tendency to wait
before reissuing packages.  Subpackages may lower the workload for a
small Docs team -- you could only issue a quarterly update, or on some
other regular but liveable basis -- but arguably at the cost of
friction with the translation teams.

I also think subpackaging makes life harder for the Docs team member
responsible for a Guide.  The job of coordinating translations for a
specific mass release in one big package is quite a bit more wearying
than pushing out updated translations onesie-twosie style as they
come.  (Package rebuilds and pushes are generally very easy with our
tools.)

Just some food for thought.  And of course, it would have been great
to have this stuff considered way back when in the requirements phase
for the tool, but hindsight, and all that.  Hope this information
helps the Docs team.

I'm cc'ing Spot because I don't know if he's on this list.

-- 
Paul W. Frields                                http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
  http://redhat.com/   -  -  -  -   http://pfrields.fedorapeople.org/
  irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20090331/6bcf3e63/attachment.sig>