2 short-description: Contributing to GStreamer
5 # Contributing to GStreamer
7 This document provides instructions and guidelines for submitting issues,
8 feature requests and patches to GStreamer. The following applies to all
11 - Please use [freedesktop.org GitLab][gitlab] to perform any of the aforementioned
12 operations. You will need to create a freedesktop.org GitLab account if you
13 don't have one yet (yep, that's just how it is. Sorry for the inconvenience)
14 If you don't want to create a new account you should also be able to sign in
15 with a Google, GitHub or Twitter account.
17 ## How to File Issues and Request for Enhancements
19 ### Where to File Issues and Feature Requests
21 - Create a new issue if there is no existing report for this problem yet.
22 The GStreamer [bugs page][bugs] also has shortcuts for the major components
23 and simple search functionality if you'd like to browse or search for
24 existing issues, or use the [GitLab search bar for the GStreamer project][gitlab]
25 at the top of the page.
27 - If you are filing a feature request (i.e. anything that is not supposed to
28 work already, that is anything not an issue), please add the *Enhancement* label.
29 Feel free to add any other appropriate already existing labels. Please don't
30 create new labels just for your issue. This won't affect the way we prioritise
31 the issue, but it will make triaging easier for us. In particular, do not add
32 the *Blocker* label to an issue just because an issue is important to you.
33 This label should be added only by GStreamer maintainers.
35 - If your issue is about a specific plugin, element or utility library,
36 please prefix the issue summary with `element-name:`, `plugin-name:` or `lib:`
37 and keep the rest of the description as short and precise as possible.
41 - `id3demux: fails to extract composer tags`
42 - `tsdemux: does not detect audio stream`
43 - `Internal flow error when playing matroska file`
45 This makes sure developers looking through the list of open issues or issue
46 notification mails can quickly identify what your issue is about. If your text
47 is too long and only contains fill words at the beginning, the important
48 information will be cut off and not show up in the list view or mail client.
50 - If you don't know which component to file the issue against, just pick the one
51 that seems the most likely to you, or file it against the gstreamer-project
52 component. If in doubt just pop into our IRC channel `#gstreamer` on the
53 [OFTC IRC network](https://www.oftc.net/), which you can connect to using
54 any IRC client application or the [OFTC IRC webchat](https://webchat.oftc.net/?channels=%23gstreamer).
55 In any case, if it's not the right component someone will move the issue
56 once they have a better idea what the problem is and where it belongs.
60 - what version of GStreamer you are using
61 - what operating system you are using (Windows, macOS, Linux)
62 - if you're on Linux, please mention your distro and distro version
63 - if this is on an embedded device please provide details
65 - Try to describe how the issue can be reproduced. If it is triggered by any
66 specific file, try to make the file available somewhere for download and
67 put the link into the issue. The easier it is for us to reproduce
68 the issue, the easier it is to fix it.
70 - If you experience a crash (that is: the application shuts down unexpectedly,
71 usually with a segfault or bus error or memory access violation or such),
72 please try to [obtain a stack trace][stack-trace]. If there are criticals
73 or warnings printed right before the crash, run with the environment variable
74 `G_DEBUG=fatal_warnings` set, then it will abort on the first warning, which
75 should hopefully give an indication to where the problem is. You can then
76 obtain a stack trace from where it aborts.
78 - If the application errors out, please provide a gst debug log. You can get
79 one by setting the `GST_DEBUG=*:6` environment variable, combined with
80 `GST_DEBUG_FILE=/tmp/dbg.log`. The resulting file might end up being very
81 large, so it's advisable to compress it with `xz -9 /tmp/dbg.log` before
82 sharing. You may also be asked to provide debug logs for specific debug
83 categories rather than everything (`*:6`).
85 [stack-trace]: https://wiki.gnome.org/Community/GettingInTouch/Bugzilla/GettingTraces/Details
87 ## How to Submit Patches
89 ### Where to Submit Patches
91 Patches need to be submitted through [GitLab][gitlab] in form of a
92 "Merge Request" (MR), which is the same as a "Pull Request" (PR)
93 in GitHub, and uses the same [workflow][gitlab-merge-request-workflow].
95 [gitlab-merge-request-workflow]: https://docs.gitlab.com/ce/user/project/merge_requests/index.html#overview
97 In order to submit a merge request you first need a personal fork of the
98 project / gstreamer module in question. To fork a module go to
99 the module in question (e.g. <https://gitlab.freedesktop.org/gstreamer/gstreamer>)
100 and hit the fork button. A new repository will be created in your user namespace
101 (<https://gitlab.freedesktop.org/$USERNAME/gstreamer>). You will be redirected
102 there automatically once the forking process is finished. For big repositories
103 the forking might take a few minutes.
105 Once this is done you can add your personal fork as new remote to your existing checkout with
107 git remote add my-personal-gitlab-fork git@gitlab.freedesktop.org:$USERNAME/gstreamer.git
111 git fetch my-personal-gitlab-fork
113 that it is accessible and working.
115 If you have not done so already, you may need to first
116 [set up SSH keys in your GitLab User Settings](https://gitlab.freedesktop.org/profile/keys).
118 **Once you have done that, please make your repository public.** By default
119 newly-forked repositories might be private, but that causes problems for
120 maintainers and merge bots, so please go to the newly-created repository's
121 settings (https://gitlab.freedesktop.org/$USERNAME/gstreamer/edit) and set
122 the visibility to public. Thanks!
124 Next, you make a git branch with one or more commits you want to submit
125 for review and merging. For that you will first need a local branch which
126 you can create with e.g.
128 git checkout -b fix-xyz
130 You can then push that branch to your personal fork git repository with
132 git push my-personal-gitlab-fork
136 git push --dry-run my-personal-gitlab-fork
138 for testing to see what would happen without actually doing anything yet.
140 After you have pushed the branch to your personal fork you will see a link
141 on the terminal with which you can create a merge request for the upstream
142 repository. You can also do this later by going to the
143 branch list of your personal repository at
144 <https://gitlab.freedesktop.org/$USERNAME/gstreamer/branches>
145 and then hitting the 'Merge Request' button when ready. This will open a new
146 page where you can enter a description of the changes you are submitting.
148 Couple of additional points:
150 - If you are submitting a Merge Request for an issue (or multiple issues) that
151 already exist, please add 'Fixes #123' to the commit message of one of your
152 commits, so that there is a cross-reference in GitLab and the issue will be
153 closed automatically when your Merge Request is merged.
155 - You do not have to file an issue to go with each Merge Request, it's fine
156 to just submit a Merge Request on its own.
158 - **Please make sure the "Allow commits from members who can merge to the target branch"**
159 **checkbox is enabled when submitting merge requests** as otherwise
160 maintainers (and our merge bot) can't rebase your Merge Request when they
161 want to merge it, which means they won't be able to merge it. If you can't
162 enable the check box that means your personal repository fork is private.
163 In that case, please go to the settings and change visibility to public.
165 - If your proposed changes are proposed for review but not ready to be merged
166 yet, please prefix the Merge Request title with `WIP:` for Work-in-Progress.
167 That will prevent us from inadvertently merging it and make clear its status.
169 - Please make sure the 'Author' field in your commit messages has your full and
170 proper name and e-mail address. You can check with e.g. `git log` or `gitk`.
172 - If your change is for an enhancement (anything that is not supposed to work
173 already, i.e. anything not a bug) or adds new API, please add the
174 *Enhancement* label. This won't affect the way we prioritise your issue,
175 but it does make triaging easier for us.
177 - If your Merge Request is against a specific plugin or element or utility library,
178 please prefix the Merge Request summary with `element-name:`, `plugin-name:`
179 or `lib:` and keep the rest of the description as short and precise as possible.
183 - `id3demux: add support for WCOP frame`
184 - `riff: add RGB16 support`
185 - `playbin: detect if video-sink supports deinterlacing`
186 - `tests: rtprtx unit test is racy`
188 This makes sure developers looking through the list of open merge requests or
189 notification mails can quickly identify what your change is about. If your text
190 is too long and only contains fill words at the beginning, the important
191 information will be cut off and not show up in the list view or mail client.
193 - Make liberal use of the reference syntax available to help cross-linking
194 different issues and merge requests. e.g. `#100` references issue 100 in the
195 current module. `!100` references merge request 100 in the current project.
196 A complete list is available from [gitlab's documentation][special-md-references].
198 - Please create separate merge requests for separate issues and for different
199 modules. There is no golden rule when something counts as a separate issue,
200 please just use your best judgment. If a merge request is related to another
201 merge request in another module please mention that in the description using
202 a gitlab reference as outlined above. For example, if you have a change that
203 needs to be done in each module, one issue with one merge request per module
204 is fine. If there is an issue that requires related fixes in multiple elements
205 or libraries, please also feel free to put everything into one issue. If you
206 just happen to have multiple patches for us but they are not really related,
207 please put them in separate issues and merge requests. The main question is
208 if it makes sense to discuss and review these patches together or if they
209 could just as well be handled completely separately.
211 - Please do not send patches to the gstreamer-devel mailing list. Patches
212 submitted on the mailing list are most likely going to be ignored, overlooked,
213 or you will get a brief reply asking you to put them into gitlab. We do
214 not use the mailing list for patch review.
216 - Please do not send pull requests to our github mirror. They will be closed
219 - Please do not attach patches to existing bugs on [GNOME Bugzilla][bugzilla]
220 If you want to reopen an already closed bug, let one of the developers know
221 and we will look into that on a case-by-case basis.
223 - Please do not attach patches to issues.
226 [special-md-references]: https://docs.gitlab.com/ee/user/markdown.html#special-gitlab-references
227 [bugzilla]: https://bugzilla.gnome.org/
228 [bugs]: https://gstreamer.freedesktop.org/bugs/
229 [gitlab]: https://gitlab.freedesktop.org/gstreamer
231 ### How to Prepare a Merge Request for Submission
233 Please prepare any merge request against a current git checkout of the
234 GStreamer monorepo (gstreamer module), against the tip of the `main` branch.
235 If a merge request is prepared against an old commit or older branch and can't
236 be easily rebased you may be asked to rebase and update the branch on top of
239 If you have created a new plugin, please submit a merge request that adds it to
240 `subprojects/gst-plugins-bad`, including any required `meson.build` modifications,
241 new files and documentation.
243 #### Preparation: create a personal fork of the git repository on GitLab
245 The easiest way to create a merge request is to create one or more local commits
246 for your changes in a branch in a local git repository. This should be a git
247 clone checkout of your fork of the module in question. To fork a module go to
248 the module in question (e.g. <https://gitlab.freedesktop.org/gstreamer/gstreamer>)
249 and hit the fork button. A new repository will be created in your user namespace
250 and should be accessible as
251 <https://gitlab.freedesktop.org/$USERNAME/gstreamer>.
253 Clone the main gstreamer repository, like this:
255 git clone https://gitlab.freedesktop.org/gstreamer/gstreamer.git
257 and then add your personal fork as a git remote like this:
259 git remote add my-personal-gitlab-fork git@gitlab.freedesktop.org:$USERNAME/gstreamer.git
263 git fetch my-personal-gitlab-fork
265 that it is accessible and working.
267 If you have not done so already, you may need to first
268 [set up SSH keys in your GitLab User Settings](https://gitlab.freedesktop.org/profile/keys).
270 #### Creating a branch for the merge request and adding commits to it
272 Once you have a git repository with the original code in it, you should create a
273 branch for your change. e.g. to create a branch and checkout:
275 git checkout -b topic-branch
277 Then you can make your modifications and create a local commit with e.g.
279 git commit path/to/file1.[ch]
281 This will pop up an editor where you can create your commit message. It should
284 exampledemux: fix seeking without index in push mode
286 Without an index we would refuse to seek in push mode. Make
287 seeking without an index work by estimating the position
288 to seek to. It might not be 100% accurate, but better than
291 Then exit the editor, and you should have a commit.
293 It's best to run `git add` or `git commit` on specific directories or files
294 instead of using `git commit -a`, as it's too easy to accidentally contaminate
295 a patch with changes that belong into it with `git commit -a`, in particular
296 changes to the `common` submodule.
298 You can check your commit(s) with `git show` or `git log -p` or using a GUI
299 such as `gitg` or `gitk`.
301 Make sure the author is correctly set to your full name and e-mail address.
303 If you haven't used git before, it would be a good idea to tell it who you are:
305 $ git config --global user.name "George S. Treamer"
306 $ git config --global user.email "george.s.treamer@example.com"
308 You can make changes to the last commit using:
310 - `git commit --amend` to fix up the commit message
312 - `git commit --amend --author='John You <john@you.com>'` to fix up the author
314 - `git add path/to/file1.[ch]; git commit --amend` to incorporate fixes
315 made to the files since the last commit (i.e. what shows up in `git diff`).
316 If you just want to add some of the changes, but not all of them you can
317 use `git add -p file.c`, then it will ask you for each individual change
318 whether you want to add it or leave it.
320 Once everything looks fine, push your branch to your local fork e.g. using
322 git push your-personal-gitlab-fork your-branch
324 This push will display a link to be able create a merge request from your branch.
325 Click this link and fill out the details of the merge request. You can also
326 create a merge request from an existing branch. See the
327 [gitlab documentation][create-mr] for more details.
329 Please make sure your commits are as terse and precise as possible. Do not
330 include 'clean-ups' or non-functional changes, since they distract from the
331 real changes and make things harder to review, and also lower the chances that
332 the patch will still apply cleanly to the latest version in git. If you feel
333 there are things to clean up, please submit the clean-ups as a separate patch
334 that does not contain any functional changes.
336 Try to stick to the GStreamer indentation and coding style. There is a script
337 called [`gst-indent`][gst-indent] which you can run over your `.c` or `.cpp`
338 files if you want your code auto-indented before making the patch. The script
339 requires GNU indent to be installed already. Please do _not_ run `gst-indent` on
340 header files, our header file indentation is free-form. If you build GStreamer
341 from git, a local commit hook will be installed that checks if your commit
342 conforms to the required style (also using GNU indent).
344 Different versions of GNU indent may occasionally yield slightly different
345 indentations. If that happens, please ignore any indentation changes in
346 sections of code that your patch does not touch. You can do that by staging
347 changes selectively via `git add -p`. You can bypass the local indentation
348 check hook by using `git commit -n`, but it will still be checked again later
349 when you submit your changes through GitLab for merging.
351 [gst-indent]: https://gitlab.freedesktop.org/gstreamer/gstreamer/-/blob/main/scripts/gst-indent-all
352 [create-mr]: https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.html
354 ### Writing Good Commit Messages
356 Please take the time to write good and concise commit messages.
358 The first line of each commit message should be a short and concise summary
359 of the commit. If the commit applies to a specific subsystem, library, plugin
360 or element, prefix the message with the name of the component, for example:
362 oggdemux: fix granulepos query for the old theora bitstream
366 docs: add new stream API
370 tests: video: add unit test for converting RGB to XYZ colorspace
372 This should be a *summary* of the change and _not a description_ of the change.
373 Meaning: don't say *how* you did something but *what* you fixed, improved or
374 changed, what the most important practical *effect* of the change is. Example:
376 qtdemux: fix crash when doing reverse playback in push mode (good)
380 qtdemux: use signed integer to avoid counter underrun (bad)
382 The second line of the commit message should be empty.
384 The third and following lines should contain an extensive *description* and
385 *rationale* of the change made: what was changed, what was broken, how did it
386 get fixed, what bugs or issues does this fix? And most importantly: *why* was
389 Trivial commits do not require a description, e.g. if you fix a memory leak
390 it's usually enough to just say that you fixed a leak. Maybe mention what was
391 leaked and perhaps also if it was an important leak or only happens in some
392 corner case error code path, but in any case there's no need to write a long
393 explanation why leaks are bad or why this needed fixing.
395 The important part is really what the reasoning behind the change is, since
396 that's what people want to know if they try to figure out twelve months later
397 why a line of code does what it does.
399 If the commit is related to any particular issues in gitlab, please add a
400 reference to the issue (e.g. `See #123` or `Fixes #123` if it fixes it the
401 issue). For issues in other repositories (gst-plugins-{base,good,ugly,bad} etc.)
402 please add the full issue URL to the commit message instead (or ask for the
403 issue to be moved to the monorepo gstreamer repository), e.g.
405 https://gitlab.freedesktop.org/gstreamer/gst-plugins-foo/issues/123
407 We do not use `Signed-off by:` lines in GStreamer, please create commits
410 Please do not add references to private company-internal bug trackers or
411 code repositories in commit messages.
413 ### After Submitting your Merge Request
415 Whenever you submit a new Merge Request, add a comment to an existing issue or
416 Merge Request, GitLab will send a notification e-mail to GStreamer
417 developers. This means that there is usually no need to advertise the fact that
418 you have done so in other forums such as on IRC or on the mailing list, unless
419 you have been asked to file an issue there, in which case it's nice to follow up
420 with the link to the issue.
422 Most of all, please be patient.
424 We try to review patches as quickly as possible, but there is such a high
425 volume of issues, merge requests and feature requests that it is not always
426 possible to tend to them all as quickly as we'd like. This is especially
427 true for completely new plugins or new features.
429 If you haven't received any response at all for a while (say two weeks or so),
430 do feel free to ping developers by posting a quick follow-up comment on the
431 issue or merge request.
433 If you do not get a response, this is usually not a sign of people *ignoring*
434 the issue, but usually just means that it's fallen through the cracks or
435 people have been busy with other things.
437 Most GStreamer developers have a review workflow that's driven by e-mail or
438 GitLab notifications, so posting a follow-up comment is the best way to draw
439 attention to an issue or merge request.
441 ### Updating Your Merge Request and Addressing Review Comments
443 When someone reviews your changes, they may leave review comments for
444 particular sections of code or in general. These will usually each start
445 a new "Discussion" which is basically a thread for each comment.
447 When you believe that you have addressed the issue raised in a discussion,
448 either by updating the code or answering the questions raised, you should
449 "Resolve the Discussion" using the button, ideally also leaving a comment
450 saying so (e.g. "done", "fixed", "updated", "no longer needed" or such). The
451 comment makes sure a notification e-mail is generated, which makes it easier
452 for GStreamer developers to keep track of what's happening.
454 At the top of each merge request in GitLab is a tracker with the number of
455 unresolved discussions. This way it's easy for maintainers (and yourself)
456 to see what's left to do and if there are any open questions/issues.
458 Whenever you have made changes to your patches locally you can just
459 `git push -f your-personal-gitlab-fork your-branch` to your personal fork.
460 GitLab will then pick up the changes automatically. You do _not_ need to submit
461 a new Merge Request whenever you make changes to an already-submitted patchset,
462 and in fact you shouldn't do that because it means all the previous discussion
463 context is lost and it's also not easy for reviewers to see what changed.
464 Just force-update your existing branch.
466 You do not need to add individial "fixup commits" to your branch when you address
467 issues raised. Instead just fix up the original commit(s) directly using
468 `git rebase` etc. GitLab is able to track and show changes made between
469 different revisions of a merge request branch, so just keep the branch always
470 to the "latest clean version". See the [Rewriting History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History)
471 section of the [Pro Git book](https://git-scm.com/book/en/v2) for more details.
473 GStreamer maintainers will typically receive e-mail notifications when you add
474 a comment and when all oustanding discussions have been resolved. They may or
475 may not receive e-mail notifications when you update the commits in your branch.
477 # Workflows for GStreamer developers
479 ## Backporting to a stable branch
481 Before backporting any changes to a stable branch, they should first be
482 applied to the `main` branch, and should obviously not have caused any known
483 outstanding regressions. The only exception here are changes that do not apply
484 to the `main` branch anymore.
486 You do not need to create backport merge requests against stable branches.
487 Backport merge requests for stable branches will be created automatically
488 based on labels on `main` branch merge requests.
490 Existing merge request against the `main` branch, including merged ones,
491 that should be considered for backporting in the future should be labeled with
492 the `Needs backport` label and the label for the target stable branch
493 (e.g. `1.18`). All merge requests with the [`Needs backport`][needs-backport]
494 label will be regularly considered for backporting by GStreamer developers.
496 Changes that add API or change existing API will usually not be considered
499 In case patches don't apply cleanly to the target stable branch, draft `WIP`
500 merge requests will be created by the above-mentioned scripts. If that happens
501 developers will have to backport the desired commits and resolve any cherry-pick
502 conflicts manually. The result should then be pushed into the existing branch
503 for the `WIP` backport merge request. Any GStreamer developer should be able
504 to do this, and help in this area is always welcome. Please resolve the WIP/Draft
505 status once all the relevant commits have been backported and assign the
506 merge request to the merge bot for merging.
508 There is also a [`Maybe backport` label][maybe-backport] which can be added
509 if you're not sure if commits should be backported or not, or you want to
510 revisit it later once the changes in question have seen some testing in the
511 development branch. If you tag a merge request with `Maybe backport` it's
512 usually useful to add a comment about why it's being tagged only as a maybe.
513 That will make it easier for others to evaluate whether it should be backported
516 [needs-backport]: https://gitlab.freedesktop.org/groups/gstreamer/-/merge_requests?state=merged&label_name[]=Needs%20backport
517 [maybe-backport]: https://gitlab.freedesktop.org/groups/gstreamer/-/merge_requests?state=merged&label_name[]=Maybe%20backport