1 Moving around plug-ins between source modules
2 ---------------------------------------------
4 Last updated: 2009-08-11
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)
10 ==============================================================
11 1. How to get your plug-in out of -bad and into -good or -ugly
12 ==============================================================
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:
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
30 The three roles can be filled by two people, but not just one.
32 In addition, an admin needs to perform the actual move, which involves
37 - bug in bugzilla gets filed by someone requesting a move from bad
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 ?)
52 - should descend from an applicable base class if possible
53 - make use of GST_BOILERPLATE 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
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
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) \
77 $(GST_CFLAGS) $(CAIRO_CFLAGS)
79 - The compiled plug-in:
80 - should show up correct in gst-inspect output; no warnings, no unknown
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/liboil
88 ext/: plug-ins with external dependencies
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
97 http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-base-plugins/html/gst-plugins-base-plugins-audiotestsrc.html
99 http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-good-plugins/html/gst-plugins-good-plugins-level.html
101 - if the element has custom messages, they should be documented
102 - signals and properties should be documented
104 - The plug-in should come with tests:
105 - preferably, a unit test should be written, testing things like:
107 - push in buffers in all supported formats and verify they are handled
109 - push in buffers that trigger error cases, and verify errors are
112 for example, see gst-plugins-base/check/elements/audioconvert
114 The unit test should be put in check/elements/(nameofelement)
115 and be added to check_PROGRAMS and Makefile.am
117 - if a unit test is not appropriate (for example, device elements),
118 a test application should be written that can be run manually
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
126 - The elements should not segfault under any circumstance. This includes:
130 - The plugins need to be marked correctly for translations.
131 - All error conditions should be correctly handled using GST_ELEMENT_ERROR
132 and following practice outlined in
133 http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/gstreamer-GstGError.html
135 - message strings need to be marked for translation
136 - should be short, well-written, clear
137 - in particular, should *not* contain debug info, strerror, errno, ...
138 No, really ! NO STRERROR, NO ERRNO. If you are too lazy to provide
139 the user of your library with a nice experience, put your crap in
142 - Decision should be made if it should go into good (LGPL license,
143 LGPL dependencies, no patent issues) or ugly
145 - plugin documentation needs to be added:
146 - see gstreamer/docs/README; section on adding plugins and elements
147 - "make update" in docs/plugins and commit the new file
148 - edit -docs.sgml and add an include for the file
151 ============================================
152 2. Moving plugins with GIT (technical howto)
153 ============================================
155 Let's say we are moving the 'weneedthis' plugins from -bad/gst/weneedthis/ to
158 We want to end up with the following situation after the plugin move:
160 * weneedthis is no longer usable/visible in HEAD of -bad
161 * weneedthis is present and usable in HEAD of -good
162 * The whole history of commits concerning weneedthis are visible in -good
163 * The whole history of commits concerning weneedthis are visible in -bad
164 * If we go back to the previous release commit for -good, the 'weneedthis'
165 plugin code and commit history are not visible.
166 * If we go back to the previous release commit for -bad, the 'weneedthis'
167 plugin code and commits are visible.
170 # Four steps for moving plugins
173 For this, we use git-format-patch which will extract the various commits
174 involving the plugin we want to move into individual numbered patches.
176 > cd gst-plugins-bad.git/
177 > git format-patch -o ../patches/ --subject-prefix="MOVED FROM BAD" start..HEAD -- gst/weneedthis/ tests/check/elements/weneedthis.c
178 or (without the prefix)
179 > git format-patch -o ../patches/ --no-numbered --subject-prefix='' start..HEAD -- gst/weneedthis/ tests/check/elements/weneedthis.c
181 We can then take those patches and commit them into -good.
182 For safety, it is recommended to do all this work in a temporary branch
184 > cd ../gst-plugins-good.git/
185 > git checkout -b moving-weneedthis
186 > git am -k ../patches/*.patch
188 At this point, we have all the commits related to gst/weneedthis/ in -bad.
190 We also need to move the other related parts in:
192 * Makefile.am from intermediary directories (if needed)
196 All those modifications should be committed as one commit with an obvious
198 "Moved 'weneedthis' from -bad to -good"
199 > git commit -v -m "Moved 'weneedthis' from -bad to -good" <modified files>
201 We can now merge the branch into master and push it out for everybody.
203 > git checkout master
204 > git merge moving-weneedthis
206 The last step is to remove the plugin from the original module:
208 > git rm gst/weneedthis/
210 Remove all the code that was moved from configure, makefiles, documentations,
211 and commit that with the *SAME* commit message as the last commit we did in
213 > git commit -v -m "Moved 'weneedthis' from -bad to -good" <modified files>