#5214: Setup koji tags and repo for Docs
------------------------------+-----------------------
Reporter: crantila | Owner: rel-eng@…
Type: task | Status: new
Milestone: Fedora 18 Alpha | Component: koji
Resolution: | Keywords: docs
Blocked By: | Blocking:
------------------------------+-----------------------
Comment (by immanetize):
Hey Rudi, a few more questions, inline below.
Replying to [comment:7 rlandmann]:
> Replying to [comment:6 immanetize]:
>
> > Can you give us a high level overview of how this will work? As I
understand it, docs publishers would take content from the docs git repos
and herd it into koji to be built; a server on the other side of the
process will have a script that updates the docs it publishes when the
repo filled by our tag gets updated packages.
>
>
> Yes; that's precisely the mechanism. The only other considerations here
are that the docs packages can be made available for folk to install on
their own intranets if they want, or even on their own desktops (we build
subpackages of the docs for local installations)
>
We've been discussing shipping docs in the branch repos as well, and doing
so allows local utilities to parse them as well as the users. A -docs
subpackage that must be downloaded from docs.fedoraproject.org *and* a
document package from the f19 main repo seem redundant. RPMs only at
docs.fp.o is more work for the users, who would have to get updates
manually instead of inline with their other package updates.
> > On the packages, is there a reason to follow the form of
%{product}-%{name}-%{version}-%{format}-%{lang} for package names? To me,
it would seem more logical to let the package name just be %{name}. It
will get tedious and burdensome to task rel-eng with churning through
package names for every language, document, and release we want to
publish.
>
> Long answer, because I acknlowledge that at first it looks like a lot of
overkill :)
>
> We're deliberately setting this up to be as flexible and extensible as
possible; which means we need to consider potential namespace collisions
for packagers, and for anyone who wants to install the documentation
packages locally themselves. This is a very real risk when many of our
%{name}s are as generic as "Installation Guide".
>
> %{product} and %{version} pretty much ensure that a particular book
title remains unambiguous.
>
I facepalmed about half an hour after posting; of course, we have to have
%{version} in the name, or we can't host multiple versions at once within
the same tag.
> We package versions and languages separately to ease maintenance. For
example, a build problem in one language (because of a flaw in somebody's
PO file) should never block somebody else releasing the book in their
language. Also, a half-finished and unproofread translation should never
get published and put on public display just because another translator
finished their work long ago and is itching to release. And of course, we
don't want to block the English release because not all translations are
ready yet. Similar considerations apply to docs for specific Fedora
versions. If a translation team only completed the translation of a
particular book for F17, and has half-finished, broken translations for
F18, F16, and F15, we need to be able to publish the F17 version of the
book without also publishing broken translations for three other Fedora
releases, plus empty translations (ie, English text with Translated
headings provided by our various tools) for everything else all the way
back to FC1.
>
I'm still missing something here. Versioned packages are logical, but
language-specific ones not as much. If a translation has broken POs, we
should be able to simply not include them. Given that we keep the release
version branch as 'release ready,' for this release, we would simply limit
translations committed in the origin/f19 branch to the ones that are
sufficiently complete and that build. Broken languages only hold up the
process for as long as it takes to identify them - which we'll have to do
regardless. So, why not ship multi-lang RPMs?
> %{format} doesn't require any extra repos -- we only build two formats,
web and "desktop", and the "desktop" is a subpackage of -web-
>
> Like I said, I know it looks like a lot of overkill at first, and I
won't pretend that there isn't work for rel-eng to creating a bunch of new
repos every Fedora release. Against that, the names of these repos are
highly predictable and change only slowly from release to release; this
task should be highly automatable. Also, the package naming structure
implemented by Publican was designed around Red Hat's own practical
experience in maintaining its own docs suite over the last ten years or
so; the Publican team believes that it is "as simple as it can be, and no
simpler" ;)
--
Ticket URL: <https://fedorahosted.org/rel-eng/ticket/5214#comment:9>
Fedora Release Engineering <http://fedorahosted.org/rel-eng>
Release Engineering for the Fedora Project
--
docs mailing list
docs@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe:
https://admin.fedoraproject.org/mailman/listinfo/docs
