Let's call this an RC for the moment. Grab the tarball and have at it.
We'll call it final when I get back from vacation next week.
Also, expect a 1.11 release before long.
You can get the tarball here:
https://fedorahosted.org/released/koji/
See the changelog for full details. E.g.
git log koji-1.9.0..b8b03099c85f76ca8292a8ed99296c7d850ab22b
== Highlights ==
support extra options for tags
ability to set mock package_manager via tag extra options
optionally handle extra footer as a template
runroot plugin
support conf.d directories for hub and web
Add new {pre,post}RPMSign plugin callbacks
numerous kojira optimizations
list-history --watch
image builds using the Indirection plugin
Use iterators for potentially large queries to reduce memory use
list-tasks cli improvements
new "koji chainmaven" command
move default kojid workdir from /tmp/koji/ to /var/tmp/koji/
---
Koji supports different types of plugins.
This commit documents the 3 types that I know of, but I have absolutely
no idea if there are others.
docs/Writing_a_plugin.md | 153 +++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 153 insertions(+)
create mode 100644 docs/Writing_a_plugin.md
diff --git a/docs/Writing_a_plugin.md b/docs/Writing_a_plugin.md
new file mode 100644
index 0000000..36cddd9
--- /dev/null
+++ b/docs/Writing_a_plugin.md
@@ -0,0 +1,153 @@
+# 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
--
2.4.3
It's been eight years since koji 1.0. In that time Koji has grown a lot,
but always incrementally and with great care to avoid breaking
compatibility. Over the years, we've found numerous things that we
wanted to add or change, but that we dismissed as too big, too
complicated, or too invasive.
Bumping the major release number gives use the freedom to shake things
up a bit. Koji 2.0 is about making major changes, otherwise it would
just be koji 1.13.
Koji 2.0 will take some time. We will maintain Koji 1.x until 2.0 is
sufficiently stable. Some features (e.g. content generators) will also
appear in 1.x.
The list below is probably not complete, it is ambitious, and it is
certainly open to discussion. If you are a Koji user, or otherwise
invested in Koji, then you are encouraged to join in. I expect there
will be a lot to say, so I've created a new mailing list devoted
specifically to Koji development.
https://lists.fedorahosted.org/mailman/listinfo/koji-devel
Also, apologies for the tense summary listing. I can certain expound on
any of these as necessary. I hope this suffices to start some conversation.
= High level goals =
• better documentation
• more community involvement
• refactor/modernize code
• more modular design
∘ content generators
∘ broader, better plugin framework
• better support for different types of build processes
• better support for for different types build output
• make hard-wired restrictions more configurable
• easier to deploy
• better qa process
• better release process
= Highlights/Major changes =
• python3 support
∘ the bulk of the code will target python 2.6 + python-six
∘ we'll create a basic client lib for older systems (e.g rhel5
clients/builders)
• drop xmlrpc in favor a json based rpc
• build namespaces
∘ allow for use cases that require multiple builds of the same NVR
(or NVRA)
• refactor task scheduling
• extend content generator support
∘ content generators will land in 1.x fairly soon, but in 2.0 they
will be more integral
∘ refactor kojid to use content generator calls
∘ (possibly) tighter integration in the db
• unify handling of rpms with other build types in the db
∘ e.g. unify rpminfo and archiveinfo tables
• support different ways of building (possibly via content generators)
• utilize jsonb fields in postgres
• modular auth
∘ make it easier to add new auth mechanisms
∘ support openid auth
• improve plugins
∘ make the plugin framework cleaner and more pythonic
∘ support plugins in cli and web ui
• improve/update web ui
∘ drop cheetah templates in favor of python-jinja2
∘ more parity with cli
∘ history browsing
∘ landing page search or history
∘ support plugins
• change how tag pkglists (and blocking) work
• refactor package ownership
• refactor uploads
• more flexible gc
= Yet more changes =
• store all task requests by named args
∘ (for ease of inspection)
• get rid of tagBuild tasks
• drop odd event refererences in favor of timestamps
• streamlined cli options
• marker files for many things on disk
• more history data
• drop modpython support
• policy code
∘ more robust syntax
‣ test negation
‣ OR
‣ parentheses
‣ quoted strings
∘ multiple result policies (non-terminal actions)
∘ all-matches policy (needed for scheduler?)
∘ break action (breaks out of nesting)
∘ stop action (halts processing of an all-matches policy)
FIY:
I wrote documentation for mock-scm
https://fedoraproject.org/wiki/Projects/Mock/Plugin/Scm
I find some bugs during writing this doc and it will be fixed in next version of mock.
If you want to enhance this doc, feel free to do it.
--
Miroslav Suchy, RHCA
Red Hat, Senior Software Engineer, #brno, #devexp, #fedora-buildsys