docs/random/moving-plugins

Moving around plug-ins between source modules
---------------------------------------------

Last updated: 2005-11-18

How to get your plug-in out of -bad and into -good or -ugly
-----------------------------------------------------------

Since GStreamer 0.9.x, we have four plugin modules: -base, -good, -ugly,
and -bad.  Plug-ins are by default added to -bad.  They can only move
to -good or -ugly if a number of conditions are met:

- People involved:
  - There should be a person who is actively going to maintain this element;
    presumably this is the person writing the plug-in in the first place
  - There should be a GStreamer hacker who is willing to sponsor the element;
    this would be someone who is going to help out getting all the conditions
    met
  - There should be a core developer who verifies the merge

  The three roles can be filled by two people, but not just one.

- The plug-in's code:
  - should descend from an applicable base class if possible
  - make use of GST_BOILERPLATE macros
  - conform to the GStreamer coding style
  - use a custom debug category
  - use GST_(DEBUG/*)_OBJECT
  - use dashes in object property names to separate words
  - use correct value, name, nick for enums

- The compiled plug-in:
  - should show up correct in gst-inspect output; no warnings, no unknown
    types, ...

- The plug-in should be put in the correct location inside the module:
  sys/: plug-ins that include system headers/link to system libraries;
    usually platform-dependent as well
  gst/: plug-ins with no external dependencies, only GLib/GStreamer/liboil
  ext/: plug-ins with external dependencies

- The plug-in is documented:
  - the compiled-in descriptions should be correct
  - every element in the plug-in should have gtk-doc documentation:
    - longer description of element
    - why you would use this element
    - example launch line OR example source code
      (for example, see
       http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-base-plugins/html/gst-plugins-base-plugins-audiotestsrc.html
       for the first and
       http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-good-plugins/html/gst-plugins-good-plugins-level.html
       for the second)
    - if the element has custom messages, they should be documented
    - signals and properties should be documented

- The plug-in should come with tests:
  - preferably, a unit test should be written, testing things like:
    - setup and teardown
    - push in buffers in all supported formats and verify they are handled
      properly
    - push in buffers that trigger error cases, and verify errors are
      correctly thrown

    for example, see gst-plugins-base/check/elements/audioconvert

    The unit test should be put in check/elements/(nameofelement)
    and be added to check_PROGRAMS and Makefile.am

  - if a unit test is not appropriate (for example, device elements),
    a test application should be written that can be run manually

- The tests should be leak-free, tested with valgrind
  - the unit tests in check/ dirs are valgrinded by default
  - the manual tests should have a valgrind target
  - leaks in the supporting library (and verified to be in the supporting
    library !) can be added to suppressions files

- The elements should not segfault under any circumstance.  This includes:
  - wrong pipelines
  - bad data

- The plugins need to be marked correctly for translations.
- All error conditions should be correctly handled using GST_ELEMENT_ERROR
  and following practice outlined in
  http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/gstreamer-GstGError.html

- Decision should be made if it should go into good (LGPL license,
  LGPL dependencies, no patent issues) or ugly

- plugin documentation needs to be added:
  - "make update" in docs/plugins and commit the new file
  - edit -docs.sgml and add an include for the file