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

Dennis: We talked about this at FUDCon and you said that you had already completed part of this.

Has this been completed now?

Can you send details of the implementation, please?

Is there anything else needed from us?

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

Hi Dennis; to get started here, we will need at least these packages added to the new tag:

* publican * wkhtmltopdf * wkhtmltopdf-qt * perl-DateTime-Format-DateParse * perl-HTML-Tree * perl-XML-TreeBuilder * perl-Locale-Maketext-Gettext * publican-fedora * Fedora_Documentation-web-home * Fedora-Burning_ISO_images_to_disc-18-web-en-US * Fedora-Fedora_Live_Images-18-web-en-US * Fedora-Installation_Guide-18-web-en-US * Fedora-Installation_Quick_Start_Guide-18-web-en-US * Fedora-Musicians_Guide-18-web-en-US * Fedora-Power_Management_Guide-18-web-en-US * Fedora-Release_Notes-18-web-en-US * Fedora-Security_Guide-18-web-en-US * Fedora-Technical_Notes-18-web-en-US * Fedora-UEFI_Secure_Boot_Guide-18-web-en-US * Fedora-Virtualization_Getting_Started_Guide-18-web-en-US * Fedora-Virtualization_Security_Guide-18-web-en-US

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

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

#5214: Setup koji tags and repo for Docs ------------------------------+----------------------- Reporter: crantila | Owner: rel-eng@… Type: task | Status: new Milestone: Fedora 19 Final | Component: koji Resolution: | Keywords: docs Blocked By: | Blocking: ------------------------------+----------------------- Changes (by sparks):

* milestone: Fedora 18 Alpha => Fedora 19 Final

Comment:

Where are we on this?

#5214: Setup koji tags and repo for Docs ------------------------------+----------------------- Reporter: crantila | Owner: rel-eng@… Type: task | Status: new Milestone: Fedora 19 Final | Component: koji Resolution: | Keywords: docs Blocked By: | Blocking: ------------------------------+-----------------------

Comment (by rlandmann):

Replying to [comment:12 rlandmann]:

Should I separately request branches for those packages (and dist-git

repos for those that don't have them) or will you set that up as part of this ticket?

Actually, scratch that; after talking to AJ last week, I think that SRPM builds will be fine for everything that we need to do here.

Could you please go ahead and allow build_from_srpm and I think we're done here! :)

Cheers Rudi

#5214: Setup koji tags and repo for Docs -----------------------------+----------------------- Reporter: crantila | Owner: rel-eng@… Type: task | Status: new Milestone: Fedora 20 Beta | Component: koji Resolution: | Keywords: docs Blocked By: | Blocking: -----------------------------+-----------------------

Comment (by rlandmann):

Replying to [comment:14 immanetize]:

Is this ready? We still need to work on serving the content after Koji

builds it...

True. This ticket only covers the Koji part of the work, which is independent of the rest to some degree.