docs/random/moving-plugins

   1 Moving around plug-ins between source modules
   2 ---------------------------------------------
   3
   4 Last updated: 2006-09-01
   5
   6 How to get your plug-in out of -bad and into -good or -ugly
   7 -----------------------------------------------------------
   8
   9 Since GStreamer 0.9.x, we have four plugin modules: -base, -good, -ugly,
  10 and -bad.  Plug-ins are by default added to -bad.  They can only move
  11 to -good or -ugly if a number of conditions are met:
  12
  13 PEOPLE
  14 ------
  15 - People involved:
  16   - There should be a person who is actively going to maintain this element;
  17     presumably this is the person writing the plug-in in the first place
  18     and opening the move request
  19   - There should be a GStreamer hacker who is willing to sponsor the element;
  20     this would be someone who is going to help out getting all the conditions
  21     met, act as a mentor if necessary,...
  22   - There should be a core developer who verifies that the checklist is
  23     met
  24
  25   The three roles can be filled by two people, but not just one.
  26
  27   In addition, an admin needs to perform the actual move, which involves
  28   CVS surgery.
  29
  30 PROCESS
  31 -------
  32 - bug in bugzilla gets filed by someone requesting a move from bad
  33   to good/ugly
  34   This is "requesting" the move.
  35 - a second person reviews the request and code, and verifies that the
  36   plugin meets the checklist items below, by commenting on the bug
  37   and giving a rundown of what still needs to be done
  38   This is "sponsoring" the move.
  39 - when the checklist is met, a third person can approve the move.
  40   This is "approving" the move.
  41 - an admin performs the move.
  42   This is "performing" the move.  (Are you laughing yet ?)
  43
  44 CHECKLIST
  45 ---------
  46 - The plug-in's code:
  47   - should descend from an applicable base class if possible
  48   - make use of GST_BOILERPLATE macros
  49   - conform to the GStreamer coding style
  50   - use a custom debug category
  51   - use GST_(DEBUG/*)_OBJECT
  52   - use dashes in object property names to separate words
  53   - use correct value, name, nick for enums
  54   - use underscores in macros/function names/structs
  55     e.g.: GST_BASE_SINK, GstBaseSink, gst_base_sink_
  56   - use g_assert(), g_return_if_fail(), g_return_val_if_fail() for pre/post
  57     condition checks
  58   - must not have any functional code within g_assert(), g_return_if_fail() or
  59     g_return_val_if_fail() statements, since those would be turned into NO-OPS
  60     if the code is compiled with -DG_DISABLE_CHECKS (as is often done on
  61     embedded systems).
  62
  63 - The plug-in's build:
  64   - should be correctly integrated with configure.ac
  65   - files implementing elements should be named according to their class name,
  66     e.g GstBaseSink -> gstbasesink.c
  67   - should list libs and cflags in stack order, with lowest in the stack first
  68     (so one can link against highest in the stack somewhere else without
  69      picking up everything from the somewhere else)
  70     e.g. $(GST_PLUGINS_BASE_CFLAGS) \
  71          $(GST_BASE_CFLAGS) \
  72          $(GST_CFLAGS) $(CAIRO_CFLAGS)
  73
  74 - The compiled plug-in:
  75   - should show up correct in gst-inspect output; no warnings, no unknown
  76     types, ...
  77
  78 - The plug-in should be put in the correct location inside the module:
  79   sys/: plug-ins that include system headers/link to system libraries;
  80     usually platform-dependent as well
  81     name after whatever system "thing" they use (oss, v4l, ...)
  82   gst/: plug-ins with no external dependencies, only GLib/GStreamer/liboil
  83   ext/: plug-ins with external dependencies
  84
  85 - The plug-in is documented:
  86   - the compiled-in descriptions (element details) should be correct
  87   - every element in the plug-in should have gtk-doc documentation:
  88     - longer description of element
  89     - why you would use this element
  90     - example launch line OR example source code
  91       (for example, see
  92        http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-base-plugins/html/gst-plugins-base-plugins-audiotestsrc.html
  93        for the first and
  94        http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-good-plugins/html/gst-plugins-good-plugins-level.html
  95        for the second)
  96     - if the element has custom messages, they should be documented
  97     - signals and properties should be documented
  98
  99 - The plug-in should come with tests:
 100   - preferably, a unit test should be written, testing things like:
 101     - setup and teardown
 102     - push in buffers in all supported formats and verify they are handled
 103       properly
 104     - push in buffers that trigger error cases, and verify errors are
 105       correctly thrown
 106
 107     for example, see gst-plugins-base/check/elements/audioconvert
 108
 109     The unit test should be put in check/elements/(nameofelement)
 110     and be added to check_PROGRAMS and Makefile.am
 111
 112   - if a unit test is not appropriate (for example, device elements),
 113     a test application should be written that can be run manually
 114
 115 - The tests should be leak-free, tested with valgrind
 116   - the unit tests in check/ dirs are valgrinded by default
 117   - the manual tests should have a valgrind target
 118   - leaks in the supporting library (and verified to be in the supporting
 119     library !) can be added to suppression files
 120
 121 - The elements should not segfault under any circumstance.  This includes:
 122   - wrong pipelines
 123   - bad data
 124
 125 - The plugins need to be marked correctly for translations.
 126 - All error conditions should be correctly handled using GST_ELEMENT_ERROR
 127   and following practice outlined in
 128   http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/gstreamer-GstGError.html
 129   - this includes:
 130     - message strings need to be marked for translation
 131     - should be short, well-written, clear
 132     - in particular, should *not* contain debug info, strerror, errno, ...
 133       No, really ! NO STRERROR, NO ERRNO.  If you are too lazy to provide
 134       the user of your library with a nice experience, put your crap in
 135       the debug string
 136
 137 - Decision should be made if it should go into good (LGPL license,
 138   LGPL dependencies, no patent issues) or ugly
 139
 140 - plugin documentation needs to be added:
 141   - see gstreamer/docs/README; section on adding plugins and elements
 142   - "make update" in docs/plugins and commit the new file
 143   - edit -docs.sgml and add an include for the file