Debian Codegraph @

docs/random/moving-plugins

raw
1 Moving around plug-ins between source modules
2 ---------------------------------------------
3
4 Last updated: 2022-06-10
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 GIT surgery.
34
35 PROCESS
36 -------
37 - Issue in gitlab 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 Meson buildsystem
70 - files implementing elements should be named according to their class name,
71 e.g GstBaseSink -> gstbasesink.c
72
73 - The compiled plug-in:
74 - should show up correct in gst-inspect output; no warnings, no unknown
75 types, ...
76
77 - The plug-in should be put in the correct location inside the module:
78 sys/: plug-ins that include system headers/link to system libraries;
79 usually platform-dependent as well
80 name after whatever system "thing" they use (oss, v4l, ...)
81 gst/: plug-ins with no external dependencies, only GLib/GStreamer/liborc
82 ext/: plug-ins with external dependencies
83
84 - The plug-in is documented:
85 - the compiled-in descriptions (element details) should be correct
86 - every element in the plug-in should have gtk-doc documentation:
87 - longer description of element
88 - why you would use this element
89 - example launch line OR example source code
90 (for example, see
91 http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-base-plugins/html/gst-plugins-base-plugins-audiotestsrc.html
92 for the first and
93 http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-good-plugins/html/gst-plugins-good-plugins-level.html
94 for the second)
95 - if the element has custom messages, they should be documented
96 - signals and properties should be documented
97
98 - The plug-in should come with tests:
99 - preferably, a unit test should be written, testing things like:
100 - setup and teardown
101 - push in buffers in all supported formats and verify they are handled
102 properly
103 - push in buffers that trigger error cases, and verify errors are
104 correctly thrown
105
106 for example, see gst-plugins-base/check/elements/audioconvert
107
108 The unit test should be put in check/elements/(nameofelement)
109 and be added to check_PROGRAMS and Makefile.am
110
111 - if a unit test is not appropriate (for example, device elements),
112 a test application should be written that can be run manually
113
114 - The tests should be leak-free, tested with valgrind
115 - the unit tests in check/ dirs are valgrinded by default
116 - the manual tests should have a valgrind target
117 - leaks in the supporting library (and verified to be in the supporting
118 library !) can be added to suppression files
119
120 - The elements should not segfault under any circumstance. This includes:
121 - wrong pipelines
122 - bad data
123
124 - The element must not rely on a running GLib main loop, meaning it can't
125 use g_idle_add(), g_timeout_add(), g_io_add_watch(), etc.
126
127 - The plugins need to be marked correctly for translations.
128 - All error conditions should be correctly handled using GST_ELEMENT_ERROR
129 and following practice outlined in
130 http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/gstreamer-GstGError.html
131 - this includes:
132 - message strings need to be marked for translation
133 - should be short, well-written, clear
134 - in particular, should *not* contain debug info, strerror, errno, ...
135 No, really ! NO STRERROR, NO ERRNO. If you are too lazy to provide
136 the user of your library with a nice experience, put your crap in
137 the debug string
138
139 - Decision should be made if it should go into good (LGPL license,
140 LGPL dependencies, no patent issues) or ugly
141
142 - plugin documentation needs to be added:
143 - see gstreamer/docs/README; section on adding plugins and elements
144 - "make update" in docs/plugins and commit the new file
145 - edit -docs.sgml and add an include for the file
146
147
148 ============================================
149 2. Moving plugins with GIT (technical howto)
150 ============================================
151
152 Inside the monorepo we can simply use `git mv`. Make sure to move not
153 just the plugin itself but also any relevant examples, tests, manual
154 tests, and documentation, as well as i18n bits.
155
156 In order to move plugins from an external repository with history into
157 the monorepo, we can import the plugin's git history from the repository
158 or a git bundle through a merge commit with `--allow-unrelated-histories`
159 and then move it into the right place and hook it up to the build system
160 in a follow-up commit. If the original commit hashes don't need to be
161 maintained, we can import a stripped-down version of the external repository
162 where everything non-essential has been filtered out using `git filter-*`,
163 so that we then import a repo that only has the history of the plugin code
164 and the tests we want to import, but not any auxiliary files and such.