#5214: Setup koji tags and repo for Docs

[Fedora Release Engineering]

#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 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)

 > 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.

 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.

 %{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:7>
Fedora Release Engineering <http://fedorahosted.org/rel-eng>
Release Engineering for the Fedora Project