docs/random/moving-plugins

   1 Moving around plug-ins between source modules
   2 ---------------------------------------------
   3
   4 Last updated: 2013-12-13
   5
   6 Contents:
   7   1. How to get your plug-in out of -bad and into -good or -ugly (ie. policies)
   8   2. How to move plugins between modules with git (ie. technical howto)
   9
  10 ==============================================================
  11 1. How to get your plug-in out of -bad and into -good or -ugly
  12 ==============================================================
  13
  14 Since GStreamer 0.9.x, we have four plugin modules: -base, -good, -ugly,
  15 and -bad.  Plug-ins are by default added to -bad.  They can only move
  16 to -good or -ugly if a number of conditions are met:
  17
  18 PEOPLE
  19 ------
  20 - People involved:
  21   - There should be a person who is actively going to maintain this element;
  22     presumably this is the person writing the plug-in in the first place
  23     and opening the move request
  24   - There should be a GStreamer hacker who is willing to sponsor the element;
  25     this would be someone who is going to help out getting all the conditions
  26     met, act as a mentor if necessary,...
  27   - There should be a core developer who verifies that the checklist is
  28     met
  29
  30   The three roles can be filled by two people, but not just one.
  31
  32   In addition, an admin needs to perform the actual move, which involves
  33   CVS surgery.
  34
  35 PROCESS
  36 -------
  37 - bug in bugzilla gets filed by someone requesting a move from bad
  38   to good/ugly
  39   This is "requesting" the move.
  40 - a second person reviews the request and code, and verifies that the
  41   plugin meets the checklist items below, by commenting on the bug
  42   and giving a rundown of what still needs to be done
  43   This is "sponsoring" the move.
  44 - when the checklist is met, a third person can approve the move.
  45   This is "approving" the move.
  46 - an admin performs the move.
  47   This is "performing" the move.  (Are you laughing yet ?)
  48
  49 CHECKLIST
  50 ---------
  51 - The plug-in's code:
  52   - should descend from an applicable base class if possible
  53   - make use of G_DEFINE_TYPE macros
  54   - conform to the GStreamer coding style
  55   - use a custom debug category
  56   - use GST_(DEBUG/*)_OBJECT
  57   - use dashes in object property names to separate words
  58   - use correct value, name, nick for enums
  59   - use underscores in macros/function names/structs
  60     e.g.: GST_BASE_SINK, GstBaseSink, gst_base_sink_
  61   - use g_assert(), g_return_if_fail(), g_return_val_if_fail() for pre/post
  62     condition checks
  63   - must not have any functional code within g_assert(), g_return_if_fail() or
  64     g_return_val_if_fail() statements, since those would be turned into NO-OPS
  65     if the code is compiled with -DG_DISABLE_CHECKS (as is often done on
  66     embedded systems).
  67
  68 - The plug-in's build:
  69   - should be correctly integrated with configure.ac
  70   - files implementing elements should be named according to their class name,
  71     e.g GstBaseSink -> gstbasesink.c
  72   - should list libs and cflags in stack order, with lowest in the stack first
  73     (so one can link against highest in the stack somewhere else without
  74      picking up everything from the somewhere else)
  75     e.g. $(GST_PLUGINS_BASE_CFLAGS) \
  76          $(GST_BASE_CFLAGS) \
  77          $(GST_CFLAGS) $(CAIRO_CFLAGS)
  78
  79 - The compiled plug-in:
  80   - should show up correct in gst-inspect output; no warnings, no unknown
  81     types, ...
  82
  83 - The plug-in should be put in the correct location inside the module:
  84   sys/: plug-ins that include system headers/link to system libraries;
  85     usually platform-dependent as well
  86     name after whatever system "thing" they use (oss, v4l, ...)
  87   gst/: plug-ins with no external dependencies, only GLib/GStreamer/liborc
  88   ext/: plug-ins with external dependencies
  89
  90 - The plug-in is documented:
  91   - the compiled-in descriptions (element details) should be correct
  92   - every element in the plug-in should have gtk-doc documentation:
  93     - longer description of element
  94     - why you would use this element
  95     - example launch line OR example source code
  96       (for example, see
  97        http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-base-plugins/html/gst-plugins-base-plugins-audiotestsrc.html
  98        for the first and
  99        http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-good-plugins/html/gst-plugins-good-plugins-level.html
 100        for the second)
 101     - if the element has custom messages, they should be documented
 102     - signals and properties should be documented
 103
 104 - The plug-in should come with tests:
 105   - preferably, a unit test should be written, testing things like:
 106     - setup and teardown
 107     - push in buffers in all supported formats and verify they are handled
 108       properly
 109     - push in buffers that trigger error cases, and verify errors are
 110       correctly thrown
 111
 112     for example, see gst-plugins-base/check/elements/audioconvert
 113
 114     The unit test should be put in check/elements/(nameofelement)
 115     and be added to check_PROGRAMS and Makefile.am
 116
 117   - if a unit test is not appropriate (for example, device elements),
 118     a test application should be written that can be run manually
 119
 120 - The tests should be leak-free, tested with valgrind
 121   - the unit tests in check/ dirs are valgrinded by default
 122   - the manual tests should have a valgrind target
 123   - leaks in the supporting library (and verified to be in the supporting
 124     library !) can be added to suppression files
 125
 126 - The elements should not segfault under any circumstance.  This includes:
 127   - wrong pipelines
 128   - bad data
 129
 130 - The element must not rely on a running GLib main loop, meaning it can't
 131   use g_idle_add(), g_timeout_add(), g_io_add_watch(), etc.
 132
 133 - The plugins need to be marked correctly for translations.
 134 - All error conditions should be correctly handled using GST_ELEMENT_ERROR
 135   and following practice outlined in
 136   http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/gstreamer-GstGError.html
 137   - this includes:
 138     - message strings need to be marked for translation
 139     - should be short, well-written, clear
 140     - in particular, should *not* contain debug info, strerror, errno, ...
 141       No, really ! NO STRERROR, NO ERRNO.  If you are too lazy to provide
 142       the user of your library with a nice experience, put your crap in
 143       the debug string
 144
 145 - Decision should be made if it should go into good (LGPL license,
 146   LGPL dependencies, no patent issues) or ugly
 147
 148 - plugin documentation needs to be added:
 149   - see gstreamer/docs/README; section on adding plugins and elements
 150   - "make update" in docs/plugins and commit the new file
 151   - edit -docs.sgml and add an include for the file
 152
 153
 154 ============================================
 155 2. Moving plugins with GIT (technical howto)
 156 ============================================
 157
 158 Let's say we are moving the 'weneedthis' plugins from -bad/gst/weneedthis/ to
 159 -good.
 160
 161 We want to end up with the following situation after the plugin move:
 162
 163 * weneedthis is no longer usable/visible in HEAD of -bad
 164 * weneedthis is present and usable in HEAD of -good
 165 * The whole history of commits concerning weneedthis are visible in -good
 166 * The whole history of commits concerning weneedthis are visible in -bad
 167 * If we go back to the previous release commit for -good, the 'weneedthis'
 168   plugin code and commit history are not visible.
 169 * If we go back to the previous release commit for -bad, the 'weneedthis'
 170   plugin code and commits are visible.
 171
 172
 173 # Four steps for moving plugins
 174 ----------
 175
 176 For this, we use git-format-patch which will extract the various commits
 177 involving the plugin we want to move into individual numbered patches.
 178
 179 > cd gst-plugins-bad.git/
 180 > git format-patch -o ../patches/ --subject-prefix="MOVED FROM BAD" start..HEAD -- gst/weneedthis/ tests/check/elements/weneedthis.c
 181 or (without the prefix)
 182 > git format-patch -o ../patches/ --no-numbered --subject-prefix='' start..HEAD -- gst/weneedthis/ tests/check/elements/weneedthis.c
 183
 184 We can then take those patches and commit them into -good.
 185 For safety, it is recommended to do all this work in a temporary branch
 186
 187 > cd ../gst-plugins-good.git/
 188 > git checkout -b moving-weneedthis
 189 > git am -k ../patches/*.patch
 190
 191 At this point, we have all the commits related to gst/weneedthis/ in -bad.
 192
 193 We also need to move the other related parts in:
 194 * configure.ac
 195 * Makefile.am from intermediary directories (if needed)
 196 * i18n
 197 * documentation
 198
 199 All those modifications should be committed as one commit with an obvious
 200 summary:
 201 "Moved 'weneedthis' from -bad to -good"
 202 > git commit -v -m "Moved 'weneedthis' from -bad to -good" <modified files>
 203
 204 We can now merge the branch into master and push it out for everybody.
 205
 206 > git checkout master
 207 > git merge moving-weneedthis
 208
 209 The last step is to remove the plugin from the original module:
 210
 211 > git rm gst/weneedthis/
 212
 213 Remove all the code that was moved from configure, makefiles, documentations,
 214 and commit that with the *SAME* commit message as the last commit we did in
 215 -good:
 216 > git commit -v -m "Moved 'weneedthis' from -bad to -good" <modified files>
 217