#2 first pass at converting docs to sphinx-doc reStructured Text
Closed 3 years ago by mikem. Opened 4 years ago by maxamillion.
maxamillion/koji docs  into  master

file modified
+1

@@ -1,3 +1,4 @@ 

  *.pyc

  *.pyo

  tests/test.py

+ docs/build/

file removed
-321

@@ -1,321 +0,0 @@ 

- <html xmlns="http://www.w3.org/1999/xhtml">

-   <head>

-     <title>Koji HOWTO</title>

-   </head>

-   <body>

-     <h1>Introduction</h1>

- 

-     Koji is a system for building and tracking RPMs. It was designed with the following

-     features in mind:

- 

-     <p>

-     <b>Security</b>

-     <ul>

-       <li>New buildroot for each build</li>

-       <li>nfs is used (mostly) read-only</li>

-     </ul>

- 

-     <b>Leverage other software</b>

-     <ul>

-       <li>Uses Yum and Mock open-source components</li>

-       <li>XML-RPC APIs for easy integration with other tools</li>

-     </ul>

- 

-     <b>Flexibility</b>

-     <ul>

-       <li>rich data model</li>

-       <li>active code base</li>

-     </ul>

- 

-     <b>Usability</b>

-     <ul>

-       <li>Web interface with Kerberos authentication</li>

-       <li>Thin, portable client</li>

-       <li>Users can create local buildroots</li>

-     </ul>

- 

-     <b>Reproducibility</b>

-     <ul>

-       <li>Buildroot contents are tracked in the database</li>

-       <li>Versioned data</li>

-     </ul>

- 

- 

-     <p> This HOWTO document covers the basic tasks that a developer needs to be

-     able to accomplish with Koji.

-     </p>

- 

-     <h1>Getting started</h1>

- 

-     <h2>The web interface</h2>

-     <p>The primary interface for viewing Koji data is a web application. Most of the interface

-     is read-only, but if you are logged in (see below) and have sufficient privileges there

-     are some actions that can be performed though the web. For example:

-     <ul>

-     <li>Cancel a build</li>

-     <li>Resubmit a failed task</li>

-     </ul>

-     Those with admin privileges will find additional actions, such as:

-     <ul>

-     <li>Create/Edit/Delete a tag</li>

-     <li>Create/Edit/Delete a target</li>

-     <li>Enable/Disable a build host</li>

-     </ul>

- 

-     <p>The web site utilizes Kerberos authentication. In order to log in you will

-     need a valid Kerberos ticket and your web browser will need to be configured to send the

-     Kerberos information to the server.

- 

-     <p>In Firefox or Mozilla, you will need to use the about:config page to set a few parameters.

-     Use the search term 'negotiate' to filter the list. Change

-     network.negotiate-auth.trusted-uris to the domain you want to authenticate against,

-     e.g .example.com. You can leave network.negotiate-auth.delegation-uris blank, as it

-     enables Kerberos ticket passing, which is not required. If you do not see those two

-     config options listed, your version of Firefox or Mozilla may be too old to support

-     Negotiate authentication, and you should consider upgrading.

- 

-     <p>In order to obtain a Kerberos ticket, use the kinit command.

- 

- 

-     <h2>Installing the Koji cli</h2>

-     <p>There is a single point of entry for most operations.  The command is

-     called 'koji' and is included in the main koji package.

- 

-     <p>Repos/webpage TBD

- 

-     <p>

-     The koji tool authenticates to the central server using Kerberos, so you will need

-     to have a valid Kerberos ticket to use many features. However, many of the read-only

-     commands will work without authentication.

- 

-     <h2>Building a package</h2>

-     <p>Builds are initiated with the command line tool.

-     To build a package, the syntax is:</p>

-     <pre>$ koji build &lt;build target&gt; &lt;cvs URL&gt;</pre>

- 

-     <p>For example:</p>

-     <pre>$ koji build dist-fc7-scratch 'cvs://cvs.example.com/cvs/dist?rpms/kernel/FC-7#kernel-2_6_20-1_2925_fc7'</pre>

-     <p>

-     The <code>koji build</code> command creates a build task in Koji. By default

-     the tool will wait

-     and print status updates until the build completes. You can override this with

-     the <code>--nowait</code> option. To view other options to the build command use the

-     <code>--help</code> option.

-     </p>

- 

-     <pre>$ koji build --help

- </pre>

- 

-     <h2>Build Options</h2>

-     <p>

-     There are a few options to the build command. Here are some more detailed explanations

-     of them:

-     </p>

- 

-     <dl>

-     <dt>--skip-tag</dt>

-     <dd>Normally the package is tagged after the build completes. This option causes

-     the tagging step to be skipped. The package will be in the system, but untagged

-     (you can later tag it with the tag-pkg command)</dd>

-     <dt>--scratch</dt>

-     <dd>This makes the build into a scratch build. The build will not be

-     imported into the db, it will just be built. The rpms will land under

-     &lt;topdir&gt;/scratch.  Scratch builds are not tracked and can never

-     be tagged, but can be convenient for testing. Scratch builds are

-     typically removed from the filesystem after one week.

-     </dd>

-     <dt>--nowait</dt>

-     <dd>As stated above, this prevents the cli from waiting on the build task.</dd>

-     <dt>--arch-override</dt>

-     <dd>This option allows you to override the base set of arches to build for.

-     This option is really only for testing during the beta period, but it may

-     be retained for scratch builds in the future.</dd>

-     </dl>

- 

-     <h2>Build Failures</h2>

-     <p>If your package fails to build, you will see something like this.</p>

-     <pre>

-       420066 buildArch (kernel-2.6.18-1.2739.10.9.el5.jjf.215394.2.src.rpm,

-       ia64): open (build-1.example.com) -> FAILED: BuildrootError:

-       error building package (arch ia64), mock exited with status 10

-     </pre>

- 

-     <p>You can figure out why the build failed by looking at the log files. If

-     there is a build.log, start there.  Otherwise, look at init.log</p>

- 

-     <pre>

-       $ ls -1 &lt;topdir&gt;/work/tasks/420066/*

-       &lt;topdir&gt;/work/tasks/420066/build.log

-       &lt;topdir&gt;/work/tasks/420066/init.log

-       &lt;topdir&gt;/work/tasks/420066/mockconfig.log

-       &lt;topdir&gt;/work/tasks/420066/root.log

-     </pre>

- 

-     <h2>Filing Bugs</h2>

- 

-     <p>bug tracking TBD

- 

-     <h1>Koji Architecture</h1>

- 

-     <h2>Terminology</h2>

- 

-     In Koji, it is sometimes necessary to distinguish between the a package in general,

-     a specific build of a package, and the various rpm files created by a build. When

-     precision is needed, these terms should be interpreted as follows:

- 

-     <dl>

-     <dt>Package</dt>

-     <dd>The name of a source rpm. This refers to the package in general and not

-     any particular build or subpackage. For example: kernel, glibc, etc.</dd>

-     <dt>Build</dt>

-     <dd>A particular build of a package. This refers to the entire build: all arches

-     and subpackages. For example: kernel-2.6.9-34.EL, glibc-2.3.4-2.19.</dd>

-     <dt>RPM</dt>

-     <dd>A particular rpm. A specific arch and subpackage of a build.

-     For example: kernel-2.6.9-34.EL.x86_64, kernel-devel-2.6.9-34.EL.s390,

-     glibc-2.3.4-2.19.i686, glibc-common-2.3.4-2.19.ia64</dd>

-     </dl>

- 

- 

-     <h2>Koji Components</h2>

- 

-     Koji is comprised of several components:

- 

-     <ul>

-     <li><em>koji-hub</em> is the center of all Koji operations.  It is an XML-RPC server

-     running under mod_python in Apache.  koji-hub is passive in that it only

-     receives XML-RPC calls and relies upon the build daemons and other

-     components to initiate communication.  koji-hub is the only component that

-     has direct access to the database and is one of the two components that have

-     write access to the file system.</li>

- 

-     <li><em>kojid</em> is the build daemon that runs on each of the build machines.  Its

-     primary responsibility is polling for incoming build requests and handling

-     them accordingly.  Koji also has support for tasks other than building.

-     Creating install images is one example.  kojid is responsible for handling

-     these tasks as well.

- 

-     <p>kojid uses mock for building.  It also creates a fresh buildroot for

-     every build.  kojid is written in Python and communicates with koji-hub via

-     XML-RPC.</p></li>

- 

-     <li><em>koji-web</em> is a set of scripts that run in mod_python and use the Cheetah

-     templating engine to provide an web interface to Koji.  koji-web exposes a

-     lot of information and also provides a means for certain operations, such as

-     cancelling builds.</li>

- 

-     <li><em>koji</em> is a CLI written in Python that provides many hooks into

-     Koji.  It allows the user to query much of the data as well as perform

-     actions such as build initiation.</li>

- 

-     <li><em>kojirepod</em> is a daemon that keeps the build root repodata

-     updated.</li>

- 

-     </ul>

- 

-     <h2>Package Organization</h2>

-     <p><i>Tags and Targets</i></p>

-     <p>Koji organizes packages using tags. In Koji a tag is roughly analogous to

-     a beehive collection instance, but differ in a number of ways:</p>

-     <ul>

-         <li>Tags are tracked in the database but not on disk</li>

-         <li>Tags support multiple inheritance</li>

-         <li>Each tag has its own list of valid packages (inheritable)</li>

-         <li>Package ownership can be set per-tag (inheritable)</li>

-         <li>Tag inheritance is more configurable</li>

-         <li>When you build you specify a <i>target</i> rather than a tag</li>

-     </ul>

-     <p>

-     A build target specifies where a package should be built and how it

-     should be tagged afterwards. This allows target names to remain fixed

-     as tags change through releases. You can get a full list of build targets

-     with the following command:</p>

-     <pre>$ koji list-targets

- </pre>

-     You can see just a single target with the <code>--name</code> option:

-     <pre>$ koji list-targets --name dist-fc7

- Name                           Buildroot                      Destination

- ---------------------------------------------------------------------------------------------

- dist-fc7                       dist-fc7-build                 dist-fc7

- </pre>

-     This tells you a build for target dist-fc7 will use a buildroot with packages

-     from the tag dist-fc7-build and tag the resulting packages as dist-fc7.

-     <p>

-     You can get a list of tags with the following command:</p>

-     <pre>$ koji list-tags

- </pre>

-     <p><i>Package lists</i></p>

-     <p>

-     As mentioned above, each tag has its own list of packages that may be placed

-     in the tag. To see that list for a tag, use the <code>list-pkgs</code> command:</p>

-     <pre>$ koji list-pkgs --tag dist-fc7

- Package                 Tag                     Extra Arches     Owner

- ----------------------- ----------------------- ---------------- ----------------

- ElectricFence           dist-fc6                                 pmachata

- GConf2                  dist-fc6                                 rstrode

- lucene                  dist-fc6                                 dbhole

- lvm2                    dist-fc6                                 lvm-team

- ImageMagick             dist-fc6                                 nmurray

- m17n-db                 dist-fc6                                 majain

- m17n-lib                dist-fc6                                 majain

- MAKEDEV                 dist-fc6                                 clumens

- ...

- </pre>

-     The first column is the name of the package, the second tells you which tag

-     the package entry has been inherited from, and the third tells you the owner

-     of the package.

-     <p><i>Latest Builds</i></p>

-     <p>

-     To see the latest builds for a tag, use the <code>latest-pkg</code> command:</p>

-     <pre>$ koji latest-pkg --all dist-fc7

- Build                                     Tag                   Built by

- ----------------------------------------  --------------------  ----------------

- ConsoleKit-0.1.0-5.fc7                    dist-fc7              davidz

- ElectricFence-2.2.2-20.2.2                dist-fc6              jkeating

- GConf2-2.16.0-6.fc7                       dist-fc7              mclasen

- ImageMagick-6.2.8.0-3.fc6.1               dist-fc6-updates      nmurray

- MAKEDEV-3.23-1.2                          dist-fc6              nalin

- MySQL-python-1.2.1_p2-2                   dist-fc7              katzj

- NetworkManager-0.6.5-0.3.cvs20061025.fc7  dist-fc7              caillon

- ORBit2-2.14.6-1.fc7                       dist-fc7              mclasen

- </pre>

-     The output gives you not only the latest builds, but which tag they have

-     been inherited from and who built them (note: for builds imported from beehive

-     the "built by" field may be misleading)

- 

- 

-     <h2>Exploring Koji</h2>

- 

-     <p>We've tried to make Koji self-documenting wherever possible. The command

-     line tool will print a list of valid commands and each command supports

-     <code>--help</code>. For example:</p>

- 

-     <pre>

- $ koji help

- Koji commands are:

-         build                Build a package from source

-         cancel-task          Cancel a task

-         help                 List available commands

-         latest-build         Print the latest rpms for a tag

-         latest-pkg           Print the latest builds for a tag

- ...

- $ koji build --help

- usage: koji build [options] tag URL

- (Specify the --help global option for a list of other help options)

- 

- options:

-   -h, --help            show this help message and exit

-   --skip-tag            Do not attempt to tag package

-   --scratch             Perform a scratch build

-   --nowait              Don't wait on build

- ...

- </pre>

- 

-     <h1>Getting Involved</h1>

- 

-     If you would like to be more involved with the Koji project...

- 

-     <p>Project data TBD

- 

-   </body>

- </html>

file modified
+175 -2

@@ -1,4 +1,177 @@ 

- install:

+ # Makefile for Sphinx documentation

+ #

+ 

+ # You can set these variables from the command line.

+ SPHINXOPTS    =

+ SPHINXBUILD   = sphinx-build

+ PAPER         =

+ BUILDDIR      = build

+ 

+ # User-friendly check for sphinx-build

+ ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)

+ $(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)

+ endif

+ 

+ # Internal variables.

+ PAPEROPT_a4     = -D latex_paper_size=a4

+ PAPEROPT_letter = -D latex_paper_size=letter

+ ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source

+ # the i18n builder cannot share the environment and doctrees with the others

+ I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source

+ 

+ .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext

+ 

+ help:

+ 	@echo "Please use \`make <target>' where <target> is one of"

+ 	@echo "  html       to make standalone HTML files"

+ 	@echo "  dirhtml    to make HTML files named index.html in directories"

+ 	@echo "  singlehtml to make a single large HTML file"

+ 	@echo "  pickle     to make pickle files"

+ 	@echo "  json       to make JSON files"

+ 	@echo "  htmlhelp   to make HTML files and a HTML help project"

+ 	@echo "  qthelp     to make HTML files and a qthelp project"

+ 	@echo "  devhelp    to make HTML files and a Devhelp project"

+ 	@echo "  epub       to make an epub"

+ 	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"

+ 	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"

+ 	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"

+ 	@echo "  text       to make text files"

+ 	@echo "  man        to make manual pages"

+ 	@echo "  texinfo    to make Texinfo files"

+ 	@echo "  info       to make Texinfo files and run them through makeinfo"

+ 	@echo "  gettext    to make PO message catalogs"

+ 	@echo "  changes    to make an overview of all changed/added/deprecated items"

+ 	@echo "  xml        to make Docutils-native XML files"

+ 	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"

+ 	@echo "  linkcheck  to check all external links for integrity"

+ 	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"

  

  clean:

- 	rm -f *.o *.so *.pyc *~

+ 	rm -rf $(BUILDDIR)/*

+ 

+ html:

+ 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html

+ 	@echo

+ 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

+ 

+ dirhtml:

+ 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml

+ 	@echo

+ 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."

+ 

+ singlehtml:

+ 	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml

+ 	@echo

+ 	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."

+ 

+ pickle:

+ 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle

+ 	@echo

+ 	@echo "Build finished; now you can process the pickle files."

+ 

+ json:

+ 	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json

+ 	@echo

+ 	@echo "Build finished; now you can process the JSON files."

+ 

+ htmlhelp:

+ 	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp

+ 	@echo

+ 	@echo "Build finished; now you can run HTML Help Workshop with the" \

+ 	      ".hhp project file in $(BUILDDIR)/htmlhelp."

+ 

+ qthelp:

+ 	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp

+ 	@echo

+ 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \

+ 	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"

+ 	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Koji.qhcp"

+ 	@echo "To view the help file:"

+ 	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Koji.qhc"

+ 

+ devhelp:

+ 	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp

+ 	@echo

+ 	@echo "Build finished."

+ 	@echo "To view the help file:"

+ 	@echo "# mkdir -p $$HOME/.local/share/devhelp/Koji"

+ 	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Koji"

+ 	@echo "# devhelp"

+ 

+ epub:

+ 	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub

+ 	@echo

+ 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."

+ 

+ latex:

+ 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex

+ 	@echo

+ 	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."

+ 	@echo "Run \`make' in that directory to run these through (pdf)latex" \

+ 	      "(use \`make latexpdf' here to do that automatically)."

+ 

+ latexpdf:

+ 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex

+ 	@echo "Running LaTeX files through pdflatex..."

+ 	$(MAKE) -C $(BUILDDIR)/latex all-pdf

+ 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."

+ 

+ latexpdfja:

+ 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex

+ 	@echo "Running LaTeX files through platex and dvipdfmx..."

+ 	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja

+ 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."

+ 

+ text:

+ 	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text

+ 	@echo

+ 	@echo "Build finished. The text files are in $(BUILDDIR)/text."

+ 

+ man:

+ 	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man

+ 	@echo

+ 	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."

+ 

+ texinfo:

+ 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo

+ 	@echo

+ 	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."

+ 	@echo "Run \`make' in that directory to run these through makeinfo" \

+ 	      "(use \`make info' here to do that automatically)."

+ 

+ info:

+ 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo

+ 	@echo "Running Texinfo files through makeinfo..."

+ 	make -C $(BUILDDIR)/texinfo info

+ 	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."

+ 

+ gettext:

+ 	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale

+ 	@echo

+ 	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."

+ 

+ changes:

+ 	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes

+ 	@echo

+ 	@echo "The overview file is in $(BUILDDIR)/changes."

+ 

+ linkcheck:

+ 	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck

+ 	@echo

+ 	@echo "Link check complete; look for any errors in the above output " \

+ 	      "or in $(BUILDDIR)/linkcheck/output.txt."

+ 

+ doctest:

+ 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest

+ 	@echo "Testing of doctests in the sources finished, look at the " \

+ 	      "results in $(BUILDDIR)/doctest/output.txt."

+ 

+ xml:

+ 	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml

+ 	@echo

+ 	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."

+ 

+ pseudoxml:

+ 	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml

+ 	@echo

+ 	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

@@ -1,76 +0,0 @@ 

- Migrating to Koji 1.10

- ======================

- 

- // asciidoc formatted

- 

- The 1.10 release of Koji includes a few changes that you should consider when

- migrating.

- 

- DB Updates

- ----------

- 

- The new +tag_extra+ table tracks extra data for tags.

- 

- There is a new entry in the +channels+ table and some additions and updates to

- the +archivetypes+ table.

- 

- As in previous releases, we provide a migration script that updates the

- database.

- 

-   # psql koji koji  </usr/share/doc/koji-1.10.0/docs/schema-upgrade-1.9-1.10.sql

- 

- 

- Command line changes

- --------------------

- 

- A few commands support new arguments

- 

- * maven-build

- ** --ini : Pass build parameters via a .ini file

- ** --section : Get build parameters from this section of the .ini

- * wrapper-rpm

- ** --ini : Pass build parameters via a .ini file

- ** --section : Get build parameters from this section of the .ini

- * import

- ** --link : Attempt to hardlink instead of uploading

- * list-tagged

- ** --latest-n : Only show the latest N builds/rpms

- * list-history

- ** --watch : Monitor history data

- * edit-tag

- ** --extra : Set tag extra option

- * list-tasks

- ** --user : Only tasks for this user

- ** --arch : Only tasks for this architecture

- ** --method : Only tasks of this method

- ** --channel : Only tasks in this channel

- ** --host : Only tasks for this host

- * download-build

- ** --task-id : Interpret id as a task id

- 

- And there are three new commands

- 

- * image-build-indirection

- * maven-chain

- * runroot

- 

- 

- Other Configuration changes

- ---------------------------

- 

- The Koji web interface can now treate +extra-footer.html+ as a Cheetah template.

- This behavior can be enabled by setting the +LiteralFooter+ option to +False+ in

- the kojiweb config.

- 

- 

- RPC API Changes

- ---------------

- 

- The +readTaggedBuilds+ and +readTaggedRPMS+ now treat an integer value for the optional

- latest argument differently. Before it was simply treated as a boolean flag, which

- if true caused the call to return only the latest build for each package. Now, if

- the value is a positive integer N, it will return the N latest builds for each

- package. The behavior is unchanged for other values.

- 

- New rpc calls: +chainMaven+, +buildImageIndirection+, and +mergeScratch+

- 

@@ -1,79 +0,0 @@ 

- Migrating to Koji 1.9

- =====================

- 

- // asciidoc formatted

- 

- The 1.9 release of Koji includes a few changes that you should consider when

- migrating.

- 

- DB Updates

- ----------

- 

- ImageFactory support introduced some new archive types. These have been added to

- the +archivetypes+ table. The inaccurate +vmx+ entry has been removed.

- 

- As in previous releases, we provide a migration script that updates the

- database.

- 

-   # psql koji koji  </usr/share/doc/koji-1.9.0/docs/schema-upgrade-1.8-1.9.sql

- 

- 

- Command line changes

- --------------------

- 

- The command line interface handles configuration files a little differently. Old

- configs should work just fine, but now there are new options and enhancements.

- 

- In addition to the main configuration files, the koji cli now checks for

- +/etc/koji.conf.d+ and +~/.koji/config.d+ directories and loads any +*.conf+ files

- contained within. Also if the user specifies a directory with the +-c/--config+

- option, then that directory will be processed similarly.

- 

- The command line supports a new +-p/--profile+ option to select alternate configuration

- profiles without having to link or rename the koji executable.

- 

- The new +image-build+ command is used to generate images using ImageFactory. The older

- spin-appliance command is now deprecated.

- 

- The +mock-config+ command no longer requires a name argument. You can still specify one

- if you want to override the default choice. It also supports new options. The

- +--latest+ option causes the resulting mock config to reference the ``latest'' repo (a

- varying symlink). The +--target+ option allows generating the config from a target name.

- 

- Other command line changes include:

- * a new +download-logs+ command

- * the +list-groups+ command now accepts event args

- * the +taginfo+ command now reports the list of comps groups for the tag

- * the fast upload feature is now used automatically if the server supports it

- 

- Other Configuration changes

- ---------------------------

- 

- There are also some minor configuration changes in other parts of Koji.

- 

- In +kojid+ the time limit for rpm builds is now configurable via the +rpmbuild_timeout+

- setting in kojid.conf. The default is 24 hours.

- 

- The +koji-gc+ tool supports two new configuration options. The +krbservice+ option allows

- you to specify the kerberos service for authentication, and the +email_domain+ option

- allows you to specify the email domain for sending gc notices.

- 

- The messagebus hub plugin now supports +timeout+ and +heartbeat+ options for the message

- bus connection.

- 

- 

- RPC API Changes

- ---------------

- 

- Most of these changes are extensions, though some of the host-only call changes are

- incompatible.

- 

- The +tagHistory+ call accepts a new named boolean option (+active+) to select only

- active/inactive entries. It also now reports the additional fields maven_build_id and

- win_build_id if builds are maven or win builds respectively.

- 

- New rpc calls: +buildImageOz+, +host.completeImageBuild+, and +host.evalPolicy+.

- 

- The host-only calls +host.moveImageBuildToScratch+ and +host.importImage+ no longer

- accept the +rpm_results+ argument. The rpm results can be embedded in the regular

- +results+ argument.

file removed
-153

@@ -1,153 +0,0 @@ 

- # Writing Koji plugins

- 

- Depending on what you are trying to do, there are different ways to write a

- Koji plugin.

- 

- Each is described in this file, by use case.

- 

- ## Adding new task types

- 

- Koji can do several things, for example build RPMs, or live CDs. Those are

- types of tasks which Koji knows about.

- 

- If you need to do something which Koji does not know yet how to do, you could

- create a Koji Builder plugin.

- 

- Such a plugin would minimally look like this:

- 

-     from koji.tasks import BaseTaskHandler

- 

-     class MyTask(BaseTaskHandler):

-         Methods = ['mytask']

-         _taskWeight = 2.0

- 

-         def handler(self, arg1, arg2, kwarg1=None):

-             self.logger.debug("Running my task...")

- 

-             # Here is where you actually do something

- 

- A few explanations on what goes on here:

- 

- * Your task needs to inherit from `koji.tasks.BaseTaskHandler`

- * Your task must have a `Methods` attribute, which is a list of the method

-   names your task can handle.

- * You can specify the weight of your task with the `_taskWeight` attribute.

-   The more intensive (CPU, IO, ...) your task is, the higher this number

-   should be.

- * The task object has a `logger` attribute, which is a Python logger with the

-   usual `debug`, `info`, `warning` and `error` methods. The messages you send

-   with it will end up in the Koji Builder logs (`kojid.log`)

- * Your task must have a `handler()` method. That is the method Koji will call

-   to run your task. It is the method that should actually do what you need. It

-   can have as many positional and named arguments as you want.

- 

- Save your plugin as e.g `mytask.py`, then install it in the Koji Builder

- plugins folder: `/usr/lib/koji-builder-plugins/`

- 

- Finally, edit the Koji Builder config file, `/etc/kojid/kojid.conf`:

- 

-     # A space-separated list of plugins to enable

-     plugins = mytask

- 

- Restart the Koji Builder service, and your plugin will be enabled.

- 

- You can try running a task from your new task type with the command-line:

- 

-     $ koji make-task mytask arg1 arg2 kwarg1

- 

- ## Exporting new API methods over XMLRPC

- 

- Koji clients talk to the Koji Hub via an XMLRPC API.

- 

- It is sometimes desirable to add to that API, so that clients can request

- things Koji does not expose right now.

- 

- Such a plugin would minimally look like this:

- 

-     def mymethod(arg1, arg2, kwarg1=None):

-         # Here is where you actually do something

- 

-     mymethod.exported = True

- 

- A few explanations on what goes on here:

- 

- * Your plugin is just a method, with whatever positional and/or named

-   arguments you need.

- * You must export your method by setting its `exported` attribute to `True`

- * The `context.session.assertPerm()` is how you ensure that the 

- 

- Save your plugin as e.g `mymethod.py`, then install it in the Koji Hub plugins

- folder: `/usr/lib/koji-hub-plugins/`

- 

- Finally, edit the Koji Hub config file, `/etc/koji-hub/hub.conf`:

- 

-     # A space-separated list of plugins to enable

-     Plugins = mymethod

- 

- Restart the Koji Hub service, and your plugin will be enabled.

- 

- You can try calling the new XMLRPC API with the Python client library:

- 

-     >>> import koji

-     >>> session = koji.ClientSession("http://koji/example.org/kojihub")

-     >>> session.mymethod(arg1, arg2, kwarg1='some value')

- 

- ### Ensuring the user has the required permissions

- 

- If you want your new XMLRPC API to require specific permissions from the user,

- all you need to do is add the following to your method:

- 

-     from koji.context import context

- 

-     def mymethod(arg1, arg2, kwarg1=None):

-         context.session.assertPerm("admin")

- 

-         # Here is where you actually do something

- 

-     mymethod.exported = True

- 

- In the example above, Koji will ensure that the user is an administrator. You

- could of course create your own permission, and check for that.

- 

- ## Running code automatically triggered on events

- 

- You might want to run something automatically when something else happens in

- Koji.

- 

- A typical example is to automatically sign a package right after a build

- finished. Another would be to send a notification to a message bus after any

- kind of event.

- 

- This can be achieved with a plugin, which would look minimally as follows:

- 

-     from koji.plugin import callback

- 

-     @callback('preTag', 'postTag')

-     def mycallback(cbtype, tag, build, user, force=False):

-         # Here is where you actually do something

- 

- A few explanations on what goes on here:

- 

- * The `@callback` decorator allows you to declare which events should trigger

-   your function. You can pass as many as you want. For a list of supported

-   events, see `koji/plugins.py`.

- * The arguments of the function depend on the event you subscribed to. As a

-   result, you need to know how it will be called by Koji. You probably should

-   use `*kwargs` to be safe. You can see how callbacks are called in the

-   `hub/kojihub.py` file, search for calls of the `run_callbacks` function.

- 

- Save your plugin as e.g `mycallback.py`, then install it in the Koji Hub

- plugins folder: `/usr/lib/koji-hub-plugins`

- 

- Finally, edit the Koji Hub config file, `/etc/koji-hub/hub.conf`:

- 

-     # A space-separated list of plugins to enable

-     Plugins = mycallback

- 

- Restart the Koji Hub service, and your plugin will be enabled.

- 

- You can try triggering your callback plugin with the command-line. For

- example, if you registered a callback for the `postTag` event, try tagging a

- build:

- 

-     $ koji tag-build mytag mypkg-1.0-1

file added
+342

@@ -0,0 +1,342 @@ 

+ ==========

+ Koji HOWTO

+ ==========

+ 

+ Introduction

+ ============

+ 

+ Koji is a system for building and tracking RPMs. It was designed with

+ the following features in mind:

+ 

+ **Security**

+ 

+ -  New buildroot for each build

+ -  nfs is used (mostly) read-only

+ 

+ **Leverage other software**

+ 

+ -  Uses Yum and Mock open-source components

+ -  XML-RPC APIs for easy integration with other tools

+ 

+ **Flexibility**

+ 

+ -  rich data model

+ -  active code base

+ 

+ **Usability**

+ 

+ -  Web interface with Kerberos authentication

+ -  Thin, portable client

+ -  Users can create local buildroots

+ 

+ **Reproducibility**

+ 

+ -  Buildroot contents are tracked in the database

+ -  Versioned data

+ 

+ This HOWTO document covers the basic tasks that a developer needs to be

+ able to accomplish with Koji.

+ 

+ Getting started

+ ===============

+ 

+ The web interface

+ -----------------

+ 

+ The primary interface for viewing Koji data is a web application. Most

+ of the interface is read-only, but if you are logged in (see below) and

+ have sufficient privileges there are some actions that can be performed

+ though the web. For example:

+ 

+ -  Cancel a build

+ -  Resubmit a failed task

+ 

+ Those with admin privileges will find additional actions, such as:

+ 

+ -  Create/Edit/Delete a tag

+ -  Create/Edit/Delete a target

+ -  Enable/Disable a build host

+ 

+ The web site utilizes Kerberos authentication. In order to log in you

+ will need a valid Kerberos ticket and your web browser will need to be

+ configured to send the Kerberos information to the server.

+ 

+ In Firefox or Mozilla, you will need to use the about:config page to set

+ a few parameters. Use the search term 'negotiate' to filter the list.

+ Change network.negotiate-auth.trusted-uris to the domain you want to

+ authenticate against, e.g .example.com. You can leave

+ network.negotiate-auth.delegation-uris blank, as it enables Kerberos

+ ticket passing, which is not required. If you do not see those two

+ config options listed, your version of Firefox or Mozilla may be too old

+ to support Negotiate authentication, and you should consider upgrading.

+ 

+ In order to obtain a Kerberos ticket, use the kinit command.

+ 

+ Installing the Koji cli

+ -----------------------

+ 

+ There is a single point of entry for most operations. The command is

+ called 'koji' and is included in the main koji package.

+ 

+ Repos/webpage TBD

+ 

+ The koji tool authenticates to the central server using Kerberos, so you

+ will need to have a valid Kerberos ticket to use many features. However,

+ many of the read-only commands will work without authentication.

+ 

+ Building a package

+ ------------------

+ 

+ Builds are initiated with the command line tool. To build a package, the

+ syntax is:

+ 

+ ::

+ 

+     $ koji build <build target> <cvs URL>

+ 

+ For example:

+ 

+ ::

+ 

+     $ koji build dist-fc7-scratch 'cvs://cvs.example.com/cvs/dist?rpms/kernel/FC-7#kernel-2_6_20-1_2925_fc7'

+ 

+ The ``koji build`` command creates a build task in Koji. By default the

+ tool will wait and print status updates until the build completes. You

+ can override this with the ``--nowait`` option. To view other options to

+ the build command use the ``--help`` option.

+ 

+ ::

+ 

+     $ koji build --help

+ 

+ Build Options

+ -------------

+ 

+ There are a few options to the build command. Here are some more

+ detailed explanations of them:

+ 

+ ``--skip-tag``

+     Normally the package is tagged after the build completes. This

+     option causes the tagging step to be skipped. The package will be in

+     the system, but untagged (you can later tag it with the tag-pkg

+     command)

+ ``--scratch``

+     This makes the build into a scratch build. The build will not be

+     imported into the db, it will just be built. The rpms will land

+     under <topdir>/scratch. Scratch builds are not tracked and can never

+     be tagged, but can be convenient for testing. Scratch builds are

+     typically removed from the filesystem after one week.

+ ``--nowait``

+     As stated above, this prevents the cli from waiting on the build

+     task.

+ ``--arch-override``

+     This option allows you to override the base set of arches to build

+     for. This option is really only for testing during the beta period,

+     but it may be retained for scratch builds in the future.

+ 

+ Build Failures

+ --------------

+ 

+ If your package fails to build, you will see something like this.

+ 

+ ::

+ 

+           420066 buildArch (kernel-2.6.18-1.2739.10.9.el5.jjf.215394.2.src.rpm,

+           ia64): open (build-1.example.com) -> FAILED: BuildrootError:

+           error building package (arch ia64), mock exited with status 10

+ 

+ You can figure out why the build failed by looking at the log files. If

+ there is a build.log, start there. Otherwise, look at init.log

+ 

+ ::

+ 

+           $ ls -1 <topdir>/work/tasks/420066/*

+           <topdir>/work/tasks/420066/build.log

+           <topdir>/work/tasks/420066/init.log

+           <topdir>/work/tasks/420066/mockconfig.log

+           <topdir>/work/tasks/420066/root.log

+ 

+ 

+ Filing Bugs

+ -----------

+ 

+ bug tracking TBD

+ 

+ Koji Architecture

+ =================

+ 

+ Terminology

+ -----------

+ 

+ In Koji, it is sometimes necessary to distinguish between the a package

+ in general, a specific build of a package, and the various rpm files

+ created by a build. When precision is needed, these terms should be

+ interpreted as follows:

+ 

+ Package

+     The name of a source rpm. This refers to the package in general and

+     not any particular build or subpackage. For example: kernel, glibc,

+     etc.

+ Build

+     A particular build of a package. This refers to the entire build:

+     all arches and subpackages. For example: kernel-2.6.9-34.EL,

+     glibc-2.3.4-2.19.

+ RPM

+     A particular rpm. A specific arch and subpackage of a build. For

+     example: kernel-2.6.9-34.EL.x86\_64, kernel-devel-2.6.9-34.EL.s390,

+     glibc-2.3.4-2.19.i686, glibc-common-2.3.4-2.19.ia64

+ 

+ Koji Components

+ ---------------

+ 

+ Koji is comprised of several components:

+ 

+ -  **koji-hub** is the center of all Koji operations. It is an XML-RPC

+    server running under mod\_python in Apache. koji-hub is passive in

+    that it only receives XML-RPC calls and relies upon the build daemons

+    and other components to initiate communication. koji-hub is the only

+    component that has direct access to the database and is one of the

+    two components that have write access to the file system.

+ -  **kojid** is the build daemon that runs on each of the build machines.

+    Its primary responsibility is polling for incoming build requests and

+    handling them accordingly. Koji also has support for tasks other than

+    building. Creating install images is one example. kojid is

+    responsible for handling these tasks as well.

+ 

+    kojid uses mock for building. It also creates a fresh buildroot for

+    every build. kojid is written in Python and communicates with

+    koji-hub via XML-RPC.

+ 

+ -  **koji-web** is a set of scripts that run in mod\_python and use the

+    Cheetah templating engine to provide an web interface to Koji.

+    koji-web exposes a lot of information and also provides a means for

+    certain operations, such as cancelling builds.

+ -  **koji** is a CLI written in Python that provides many hooks into Koji.

+    It allows the user to query much of the data as well as perform

+    actions such as build initiation.

+ -  **kojirepod** is a daemon that keeps the build root repodata updated.

+ 

+ Package Organization

+ --------------------

+ 

+ **Tags and Targets**

+ 

+ Koji organizes packages using tags. In Koji a tag is roughly analogous

+ to a beehive collection instance, but differ in a number of ways:

+ 

+ -  Tags are tracked in the database but not on disk

+ -  Tags support multiple inheritance

+ -  Each tag has its own list of valid packages (inheritable)

+ -  Package ownership can be set per-tag (inheritable)

+ -  Tag inheritance is more configurable

+ -  When you build you specify a *target* rather than a tag

+ 

+ A build target specifies where a package should be built and how it

+ should be tagged afterwards. This allows target names to remain fixed as

+ tags change through releases. You can get a full list of build targets

+ with the following command:

+ 

+ ::

+ 

+     $ koji list-targets

+ 

+ You can see just a single target with the ``--name`` option:

+ 

+ ::

+ 

+     $ koji list-targets --name dist-fc7

+     Name                           Buildroot                      Destination

+     ---------------------------------------------------------------------------------------------

+     dist-fc7                       dist-fc7-build                 dist-fc7

+ 

+ This tells you a build for target dist-fc7 will use a buildroot with

+ packages from the tag dist-fc7-build and tag the resulting packages as

+ dist-fc7.

+ 

+ You can get a list of tags with the following command:

+ 

+ ::

+ 

+     $ koji list-tags

+ 

+ *Package lists*

+ 

+ As mentioned above, each tag has its own list of packages that may be

+ placed in the tag. To see that list for a tag, use the ``list-pkgs``

+ command:

+ 

+ ::

+ 

+     $ koji list-pkgs --tag dist-fc7

+     Package                 Tag                     Extra Arches     Owner

+     ----------------------- ----------------------- ---------------- ----------------

+     ElectricFence           dist-fc6                                 pmachata

+     GConf2                  dist-fc6                                 rstrode

+     lucene                  dist-fc6                                 dbhole

+     lvm2                    dist-fc6                                 lvm-team

+     ImageMagick             dist-fc6                                 nmurray

+     m17n-db                 dist-fc6                                 majain

+     m17n-lib                dist-fc6                                 majain

+     MAKEDEV                 dist-fc6                                 clumens

+     ...

+ 

+ The first column is the name of the package, the second tells you which

+ tag the package entry has been inherited from, and the third tells you

+ the owner of the package.

+ 

+ **Latest Builds**

+ 

+ To see the latest builds for a tag, use the ``latest-pkg`` command:

+ 

+ ::

+ 

+     $ koji latest-pkg --all dist-fc7

+     Build                                     Tag                   Built by

+     ----------------------------------------  --------------------  ----------------

+     ConsoleKit-0.1.0-5.fc7                    dist-fc7              davidz

+     ElectricFence-2.2.2-20.2.2                dist-fc6              jkeating

+     GConf2-2.16.0-6.fc7                       dist-fc7              mclasen

+     ImageMagick-6.2.8.0-3.fc6.1               dist-fc6-updates      nmurray

+     MAKEDEV-3.23-1.2                          dist-fc6              nalin

+     MySQL-python-1.2.1_p2-2                   dist-fc7              katzj

+     NetworkManager-0.6.5-0.3.cvs20061025.fc7  dist-fc7              caillon

+     ORBit2-2.14.6-1.fc7                       dist-fc7              mclasen

+ 

+ The output gives you not only the latest builds, but which tag they have

+ been inherited from and who built them (note: for builds imported from

+ beehive the "built by" field may be misleading)

+ 

+ Exploring Koji

+ --------------

+ 

+ We've tried to make Koji self-documenting wherever possible. The command

+ line tool will print a list of valid commands and each command supports

+ ``--help``. For example:

+ 

+ ::

+ 

+     $ koji help

+     Koji commands are:

+             build                Build a package from source

+             cancel-task          Cancel a task

+             help                 List available commands

+             latest-build         Print the latest rpms for a tag

+             latest-pkg           Print the latest builds for a tag

+     ...

+     $ koji build --help

+     usage: koji build [options] tag URL

+     (Specify the --help global option for a list of other help options)

+ 

+     options:

+       -h, --help            show this help message and exit

+       --skip-tag            Do not attempt to tag package

+       --scratch             Perform a scratch build

+       --nowait              Don't wait on build

+     ...

+ 

+ Getting Involved

+ ================

+ 

+ If you would like to be more involved with the Koji project...

+ 

+ Project data TBD

file added
+261

@@ -0,0 +1,261 @@ 

+ # -*- coding: utf-8 -*-

+ #

+ # Koji documentation build configuration file, created by

+ # sphinx-quickstart on Tue Nov  3 12:11:18 2015.

+ #

+ # This file is execfile()d with the current directory set to its

+ # containing dir.

+ #

+ # Note that not all possible configuration values are present in this

+ # autogenerated file.

+ #

+ # All configuration values have a default; values that are commented out

+ # serve to show the default.

+ 

+ import sys

+ import os

+ 

+ # If extensions (or modules to document with autodoc) are in another directory,

+ # add these directories to sys.path here. If the directory is relative to the

+ # documentation root, use os.path.abspath to make it absolute, like shown here.

+ #sys.path.insert(0, os.path.abspath('.'))

+ 

+ # -- General configuration ------------------------------------------------

+ 

+ # If your documentation needs a minimal Sphinx version, state it here.

+ #needs_sphinx = '1.0'

+ 

+ # Add any Sphinx extension module names here, as strings. They can be

+ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom

+ # ones.

+ extensions = [

+     'sphinx.ext.autodoc',

+     'sphinx.ext.doctest',

+ ]

+ 

+ # Add any paths that contain templates here, relative to this directory.

+ templates_path = ['_templates']

+ 

+ # The suffix of source filenames.

+ source_suffix = '.rst'

+ 

+ # The encoding of source files.

+ #source_encoding = 'utf-8-sig'

+ 

+ # The master toctree document.

+ master_doc = 'index'

+ 

+ # General information about the project.

+ project = u'Koji'

+ copyright = u'2015, Mike McLean, Mike B, Dennis Gilmore, Mathieu Bridon, Ian McLeod, Ralph Bean, Adam Miller'

+ 

+ # The version info for the project you're documenting, acts as replacement for

+ # |version| and |release|, also used in various other places throughout the

+ # built documents.

+ #

+ # The short X.Y version.

+ version = '1.10.0'

+ # The full version, including alpha/beta/rc tags.

+ release = '1.10.0'

+ 

+ # The language for content autogenerated by Sphinx. Refer to documentation

+ # for a list of supported languages.

+ #language = None

+ 

+ # There are two options for replacing |today|: either, you set today to some

+ # non-false value, then it is used:

+ #today = ''

+ # Else, today_fmt is used as the format for a strftime call.

+ #today_fmt = '%B %d, %Y'

+ 

+ # List of patterns, relative to source directory, that match files and

+ # directories to ignore when looking for source files.

+ exclude_patterns = []

+ 

+ # The reST default role (used for this markup: `text`) to use for all

+ # documents.

+ #default_role = None

+ 

+ # If true, '()' will be appended to :func: etc. cross-reference text.

+ #add_function_parentheses = True

+ 

+ # If true, the current module name will be prepended to all description

+ # unit titles (such as .. function::).

+ #add_module_names = True

+ 

+ # If true, sectionauthor and moduleauthor directives will be shown in the

+ # output. They are ignored by default.

+ #show_authors = False

+ 

+ # The name of the Pygments (syntax highlighting) style to use.

+ pygments_style = 'sphinx'

+ 

+ # A list of ignored prefixes for module index sorting.

+ #modindex_common_prefix = []

+ 

+ # If true, keep warnings as "system message" paragraphs in the built documents.

+ #keep_warnings = False

+ 

+ 

+ # -- Options for HTML output ----------------------------------------------

+ 

+ # The theme to use for HTML and HTML Help pages.  See the documentation for

+ # a list of builtin themes.

+ html_theme = 'default'

+ 

+ # Theme options are theme-specific and customize the look and feel of a theme

+ # further.  For a list of options available for each theme, see the

+ # documentation.

+ #html_theme_options = {}

+ 

+ # Add any paths that contain custom themes here, relative to this directory.

+ #html_theme_path = []

+ 

+ # The name for this set of Sphinx documents.  If None, it defaults to

+ # "<project> v<release> documentation".

+ #html_title = None

+ 

+ # A shorter title for the navigation bar.  Default is the same as html_title.

+ #html_short_title = None

+ 

+ # The name of an image file (relative to this directory) to place at the top

+ # of the sidebar.

+ #html_logo = None

+ 

+ # The name of an image file (within the static path) to use as favicon of the

+ # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32

+ # pixels large.

+ #html_favicon = None

+ 

+ # Add any paths that contain custom static files (such as style sheets) here,

+ # relative to this directory. They are copied after the builtin static files,

+ # so a file named "default.css" will overwrite the builtin "default.css".

+ html_static_path = ['_static']

+ 

+ # Add any extra paths that contain custom files (such as robots.txt or

+ # .htaccess) here, relative to this directory. These files are copied

+ # directly to the root of the documentation.

+ #html_extra_path = []

+ 

+ # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,

+ # using the given strftime format.

+ #html_last_updated_fmt = '%b %d, %Y'

+ 

+ # If true, SmartyPants will be used to convert quotes and dashes to

+ # typographically correct entities.

+ #html_use_smartypants = True

+ 

+ # Custom sidebar templates, maps document names to template names.

+ #html_sidebars = {}

+ 

+ # Additional templates that should be rendered to pages, maps page names to

+ # template names.

+ #html_additional_pages = {}

+ 

+ # If false, no module index is generated.

+ #html_domain_indices = True

+ 

+ # If false, no index is generated.

+ #html_use_index = True

+ 

+ # If true, the index is split into individual pages for each letter.

+ #html_split_index = False

+ 

+ # If true, links to the reST sources are added to the pages.

+ #html_show_sourcelink = True

+ 

+ # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.

+ #html_show_sphinx = True

+ 

+ # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.

+ #html_show_copyright = True

+ 

+ # If true, an OpenSearch description file will be output, and all pages will

+ # contain a <link> tag referring to it.  The value of this option must be the

+ # base URL from which the finished HTML is served.

+ #html_use_opensearch = ''

+ 

+ # This is the file name suffix for HTML files (e.g. ".xhtml").

+ #html_file_suffix = None

+ 

+ # Output file base name for HTML help builder.

+ htmlhelp_basename = 'Kojidoc'

+ 

+ 

+ # -- Options for LaTeX output ---------------------------------------------

+ 

+ latex_elements = {

+ # The paper size ('letterpaper' or 'a4paper').

+ #'papersize': 'letterpaper',

+ 

+ # The font size ('10pt', '11pt' or '12pt').

+ #'pointsize': '10pt',

+ 

+ # Additional stuff for the LaTeX preamble.

+ #'preamble': '',

+ }

+ 

+ # Grouping the document tree into LaTeX files. List of tuples

+ # (source start file, target name, title,

+ #  author, documentclass [howto, manual, or own class]).

+ latex_documents = [

+   ('index', 'Koji.tex', u'Koji Documentation',

+    u'Mike McLean, Mike B, Dennis Gilmore, Mathieu Bridon, Ian McLeod, Ralph Bean, Adam Miller', 'manual'),

+ ]

+ 

+ # The name of an image file (relative to this directory) to place at the top of

+ # the title page.

+ #latex_logo = None

+ 

+ # For "manual" documents, if this is true, then toplevel headings are parts,

+ # not chapters.

+ #latex_use_parts = False

+ 

+ # If true, show page references after internal links.

+ #latex_show_pagerefs = False

+ 

+ # If true, show URL addresses after external links.

+ #latex_show_urls = False

+ 

+ # Documents to append as an appendix to all manuals.

+ #latex_appendices = []

+ 

+ # If false, no module index is generated.

+ #latex_domain_indices = True

+ 

+ 

+ # -- Options for manual page output ---------------------------------------

+ 

+ # One entry per manual page. List of tuples

+ # (source start file, name, description, authors, manual section).

+ man_pages = [

+     ('index', 'koji', u'Koji Documentation',

+      [u'Mike McLean, Mike B, Dennis Gilmore, Mathieu Bridon, Ian McLeod, Ralph Bean, Adam Miller'], 1)

+ ]

+ 

+ # If true, show URL addresses after external links.

+ #man_show_urls = False

+ 

+ 

+ # -- Options for Texinfo output -------------------------------------------

+ 

+ # Grouping the document tree into Texinfo files. List of tuples

+ # (source start file, target name, title, author,

+ #  dir menu entry, description, category)

+ texinfo_documents = [

+   ('index', 'Koji', u'Koji Documentation',

+    u'Mike McLean, Mike B, Dennis Gilmore, Mathieu Bridon, Ian McLeod, Ralph Bean, Adam Miller', 'Koji', 'One line description of project.',

+    'Miscellaneous'),

+ ]

+ 

+ # Documents to append as an appendix to all manuals.

+ #texinfo_appendices = []

+ 

+ # If false, no module index is generated.

+ #texinfo_domain_indices = True

+ 

+ # How to display URL addresses: 'footnote', 'no', or 'inline'.

+ #texinfo_show_urls = 'footnote'

+ 

+ # If true, do not generate a @detailmenu in the "Top" node's menu.

+ #texinfo_no_detailmenu = False

@@ -0,0 +1,256 @@ 

+ =====================

+ Defining Hub Policies

+ =====================

+ 

+ Defining a policy on the hub allows you fine control over certain activities

+ in the system. At present, policy allows you to control:

+ * tag/untag/move operations

+ * allowing builds from srpm

+ * allowing builds from expired repos

+ * managing the package list for a tag

+ * managing which channel a task goes to

+ 

+ In the future, we expect to add more policy hooks for controlling more aspects

+ of the system.

+ 

+ Policy configuration is optional. If you don't define one, then by default:

+ * tag/untag/move operations are governed by tag locks/permissions

+ * builds from srpm are only allowed for admins

+ * builds from expired repos are only allowed for admins

+ * only admins may modify package lists

+ * tasks go to the default channel

+ 

+ Configuration

+ =============

+ 

+ The hub policy is configured in the ``hub.conf`` file, which is an ini-style

+ configuration file. Policies are defined in the section named ``[policy]``.

+ Each ``name = value`` pair defines the policy of that name. With multiple line

+ policies, successive lines should be indented so that the parser treats them

+ as part of the whole.

+ 

+ Consider the following simple (and strict) example:

+ 

+ ::

+ 

+     [policy]

+     tag =

+         has_perm admin :: allow

+         tag *-candidate :: allow

+         all :: deny

+ 

+ This policy section defines a single policy (named 'tag'). The policy is a

+ series of rules, one per line. The rule lines must be indented. Each rule is

+ a test and an action, separated by a double colon. The valid actions for

+ current policies are 'allow' and 'deny'. There are many tests available,

+ though not all of them are applicable for all policies. Each test is specified

+ by giving the name of the test followed by any arguments the test accepts.

+ 

+ Each rule in the policy is checked until a match is found. Upon finding a

+ match, the action is applied. Our example above limits non-admins to tags

+ ending in -candidate.

+ 

+ Getting a bit more complicated

+ The example above is very simple. The policy syntax also supports compound

+ tests, negated tests, and nested tests. Consider the following example:

+ 

+ ::

+ 

+     [policy]

+     tag =

+         buildtag *epel* :: {

+             tag *epel* !! deny

+         }

+         tag *-updates :: {

+             operation move :: {

+                 fromtag *-updates-candidate :: allow

+                 fromtag *-updates-testing :: allow

+                 all :: deny

+             }

+             operation tag && hastag *-updates-candidate *-updates-testing :: deny

+         }

+         all :: allow

+ 

+ This policy sets up some rules concerning tags ending in -updates and tags

+ containing epel, but is otherwise permissive.

+ 

+ The first nested rule limits builds built from a tag matching ``epel``  to only

+ such tags. Note the use of !! instead of :: negates the test.

+ 

+ For tags matching ``*-updates``, a particular work-flow is enforced. Moving is

+ only allowed if the move is coming from a tag matching ``*-updates-candidate``

+ or ``*-updates-testing``. Conversely, a basic tag operation (not a move) is

+ denied if the build also has such a tag (the policy requires a move instead).

+ 

+ General format

+ ==============

+ The general form of a basic policy line is one of the following

+ 

+ ::

+ 

+     test [params] [&& test [params] ...] :: action-if-true

+     test [params] [&& test [params] ...] !! action-if-false

+ 

+ And for nested rules:

+ 

+ ::

+ 

+     test [params] [&& ...] [::|!!] {

+         test [params] [&& ...] [::|!!] action

+         test [params] [&& ...] [::|!!] {

+             ...

+             }

+     }

+ 

+ Note that each closing brace must be on a line by itself.

+ Using ``!!`` instead of ``::`` negates the entire test.

+ Tests can only be joined with &&, the syntax does not support ``||``.

+ 

+ Available policies