On 08/08/2012 11:29 PM, Mikolaj Izdebski wrote:
Hi all,
First of all thank you for working on Fedora-Review, which was really useful
for me -- saved me a lot of time and probably improved quality of my reviews.
I would like to share my opinion on how Fedora-Review plugin API should look
like from perspective of a user who did a number of reviews and who doesn't
know the internal API.
PREAMBLE
Normal F-R workflow (simplified a lot): First you build the package and run a
number of automated tests (as part of F-R and external tools). Then go through
the review template and perform manual checks. In most cases you can't open and
read every source file, but you you'll probably end up running tools like find
and grep looking for some package-specific patterns.
After doing your n-th review you realize which parts are boring and brainless
-- you find candidates for test automation. At this point you could probably
write a custom script or a F-R plugin (using Python or JSON API).
Writing a custom plugin requires a lot of time (I know from my own experience),
so I think that the first option is definitely better. After all you remember
well all the commands you had to run, you just need to write them down in a
form of a script. You can even copy variuos parts directly from your shell
history. But running these scripts manually again and again can be
annoying. What you need is a glue between F-R and the scripts -- the API I am
proposing.
SOME ASSUMPTIONS
The API should:
1) Be easy to learn.
If you need to spend several (or more) hours to learn the F-R API and API of
JSON some JSON library then creating a custom test (plugin) may be not worth
the effort. However if you somehoe know most of the API before you even start
thinking about plugins (more about that below), creating test scripts will be
straightforward.
2) Be multilangual.
You may want to write the simplest tests in just Bourne shell, maybe more
complicated ones in other scripting languages. Also Perl SIG may want to write
tests in Perl, Python in Python, Java SIG in... anything but Java :) You can't
expect Perl proponents to write Python code only to create a plugin for F-R.
3) Backwards compatible.
If you spend some time developing a set of plugins you don't want to rewrite
them because of F-R upgrade. During upgrade from 0.1.x to 0.2.x I had to
rewrite my plugin. Hopefully I had only one and Stano helped me with the
upgrade.
4) Callback-less.
Current JSON API gives plugins only some information about package being
reviewed and requires them to call F-R back to obtain more info (like sections
of spec file). This means formating a request, reading and parsing
(semi-manually!) the reply. But this information could have been automatically
provided by F-R from the beginning! F-R should give pluging all info it has
about the package without plugins having to ask for it.
MY PROPOSAL
Basic information about packages, like name, version, type (C,Java,R,...) is
passed in exported environmental variables, which names should be compatible
with names from `rpm --querytags` if possible. More detailed information is
passed on disk in form of files. This includes things like spec file, unpacked
sources, rpmlint output, symlinks to builddir, unpacked binary rpms and so on.
Users already should know basic RPM macros like %{name} or %{epoch}, so using
env variables ($name and $epoch respectively) should be strightforward. People
that previously used F-R will be familiar with structure of directories created
by F-R (srpm-unpacked, upstream, BUILD, and so on). Test results are simply
printed on stdout. Exit code decides if test passed, failed or was inconclusive
(exit codes for that are already standardized). Attachements can be created by
creating attachement files somewhere in the filesystem.
[cut]
First of all: thanks for bringing up this issue!
Agreed: Easy to learn, mutlilingual, backwards compatible, no callbacks:
Considerations.
As noted in #96, the framework need th plugin to register it's tests.
Limiting the plugins to interpreted langauges, this could be as simple
as some greppable comments about name, info, version for each test.
The role of JSON: F-r will just start the plugin with a list of tests to
run. No json is needed for this, it only requires simple command line
parameters. Json is probably the right way to return data, though. So, a
plugin don't need to decode json, just to encode the reply.
The info: as of now, f-r already runs within a review directory with
fixed names. So, a plugin will find everything like sources, build
direcory, unpacked srpm etc at fixed paths from current directory. There
are some exceptions (notably rpmlint output), but that should be easy to
add.
However, I'm not enterily happy with the "everything in environment
variables" approach. If there is no way for the plugin to define what
it wants (parameters), the interface will expand. Just documenting it
would be ... almost wrote 'a nightmare' . Oh, did I ?
I think one thing which could work is to create Yet Another Tool (yat).
yat would just used to grab things from the review directory, doing
things like returning spec sections, built rpms etc. The interface to
this tool could be much smaller than providing everything in variables,
and also more flexible (supporting e. g, get_files_by_pattern() etc). It
could be built from existing f-r classes, with a new interface.
Summing up: a plugin sketch:
- Plugins are interpreted (have comments), not compiled.
- Comments for registration: What tests can I run, name, version, info...
- Invoked with a list of tests to run + options for debug etc. Simple
CLI interface.
- Environment variable or simple config file describes basic stuff:
type, version, name etc.
- Invoked in review dir, with all reasonable files at fixed locations
- Can (but don't need to) use the yat tool to access the data at higher
level.
- Returns a json object as today, although it can also be an error object.