[oe] a note on OE recipes and quality

[Frans Meulenbroeks]

Recently there have been some remarks on quality.
That triggered me to write down my views on quality in relation with OE.
The ideas are mine, there are no plans to enforce something at the
moment, but I would like to stir up a discussion what we find good
practices.
As a followup in due time we could come up with some rules/guidelines/whatever.
I guess quality could also be a topic at OEDEM.

As a starter let me try to identify the perfect recipe. (and of course
my analysis won't be perfect so please add).

For a recipe I see three facets wrt quality:
- functional
- the metadata
- maintenance.
Let's try to write down what a good recipe has in each of these facets
(in no particular order). Note also that not all items have the same
weight.

Functional
========
* A good recipe should build for the target/distro it is intended for
(and if it is only applicable for e.g. a specific set of machines this
is indicated with COMPATIBLE_MACHINE and friends)
If it does not build it might still be useful as a reference or as a
starter to get the recipe in good shape again, but it definitely does
not get the bits on the target moving so as such it is not too useful.
* A good recipe should also deliver what it is supposed to deliver.
E.g. if it builds but does not package any files or if the program do
no not work, the package is not too useful.
* The package, when build, should not have QA warnings, or other
(relevant) errors or warnings (e.g. files not in any package, install
errors etc etc).

Metadata
=======
* The dependency tree should be complete (but not overspecified). If
configure is used, it should reflect with what configure uses. (we
need to avoid that if you happen to build package X before even if not
in DEPENDS, that the package is configured differently because X is
found).
* configure invocation should explicitly disable packages that are not
supposed to be there.
* recipes should use a standard style/layout (e.g. as given by
oe-stylize and as described in [1]). This makes it easier to find ones
way in a recipe one is not familiar with.
* Certain fields are always present in a good recipe (e.g. LICENSE,
DESCRIPTION, HOMEPAGE etc etc)
* recipes should be as simple as possible (and not simpler). Please no
fancy python constructs unless really unavoidable. Other people should
be able to easily understand things, not having to start a puzzle as
the latter may lead to mistakes more easily
* if there is a complicated snipped of code or a specific reason to do
something in a certain way it should be mentioned in a comment.
* using BBCLASSEXTEND is encouraged, using legacy staging is discouraged


Maintenance
=========
I feel a good recipe is maintained. Tasks that a good maintainer
should perform are:
* regularly checking for new versions and make them available when
they are worthwhile
* regularly check for important patches and security advisories, and apply them
* decide on what older versions are still useful to be kept. E.g. it
might not be too useful to keep rc1, rc2, rc3 or even x.y.1, x.y.2 etc
if they are only bugfixing releases or releases with minor
enhancements. If changes are big (or e.g. footprint changes
drastically) it might be useful to keep some older versions.
* watches the mailing list and bug tracker for patches, reviews them
and applies them if correct/applicable.
* monitors the  bug reports in bugzilla. (btw: I do not see it as the
role of the maintainer to fix bugs that are also present upstream,
although it would be nice,)
* where needed: tries to get patches upstream and/or reports bugs up-stream.

[1] http://wiki.openembedded.net/index.php/Styleguide


Feel free to comment, but please keep this a friendly, open and
constructive thread.

Frans