| 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. |