SubmittingPatches

Submitting Patches

Where

Please submit patches for GStreamer in GNOME bugzilla:

Please do not submit patches on the gstreamer-devel mailing list. Patches submitted on the mailing list are most likely going to be ignored or simply overlooked.

Please also do not attach patches to already-existing bugs unless they are directly relevant to the issue, ie. do not attach patches to already-existing bugs that are only vaguely related to your issue.

How

You should prepare patches against a current git checkout, if possible at all. Patches against the current stable release of the module in question may be acceptable as well if the plugin/code hasn't changed much since then, but if it has, chances are that you will be asked to provide an updated patch against the git repository.

If you have created a new plugin, please submit a patch that adds it to gst-plugins-bad (including configure.ac and the various Makefile.am modifications and all new files).

General information on how we like our patches

Please always submit patches in 'unified context' format to make sure they are human-readable. This is the default if you are using 'git diff' or 'git format-patch' to create a patch. Otherwise, you can achieve this by passing the '-u' option to diff. Additionally, it would be quite helpful if you could also pass the '-p' option, which adds useful information to each individual patch chunk (such as the C function name). This makes patches much easier to review.

Please make sure your patches are as terse and precise as possible. Do not include 'clean-ups' or non-functional changes, since they distract from the real changes and make things harder to review (if you feel there are things to clean-up, please submit the clean-ups as a separate patch that does not contain any functional changes).

Try to stick to the GStreamer coding style (run gst-indent over your .c or .cpp files, but not the header files, if you want your code auto-indented before making the patch).

Please do not include a ChangeLog entry with your patch (feel free to suggest a wording for the ChangeLog entry in the bug report though).

Creating a diff of a single file from local changes

$ git diff path/to/file.c > mypatch.diff

or, if you are not working within a git repository (you should!): 

$ diff -u -p gst-plugins-foo-0.10.n-original/path/to/file.c gst-plugins-foo-0.10.n-modified/path/to/file.c > mypatch.diff

Creating a diff of multiple files or a whole directory

$ git diff gst/foodemux/file1.c gst/foodemux/file1.h > foodemuxpatch.diff

If you specify a directory, 'git diff' will create a patch for all modified files in the directory and all sub-directories: 

$ git diff gst/foodemux/ > foodemuxpatch.diff

The same goes for diff (note the -r option): 

$ diff -u -p -r gst-plugins-foo-0.10.n-original/gst/foodemux/ gst-plugins-foo-0.10.n-modified/gst/foodemux/ > mypatch.diff

Create a diff from a git commit

Working with a git repository is generally easier if you commit your changes locally. Unlike CVS, where commiting your changes is synonymous with sending those changes to the central repository, git has a two-stage commit process: commit the changes locally, then separately push those changes to a central repository. This allows developers to have the benefits of change control without needing write access to the central repository.

To commit changes locally, use the 'git add' and 'git commit' commands. You can add several times on various files, and then commit them all together. For example: 

$ git add file1.c
$ git add file2.c file3.h
$ git commit

The commit command will allow you to write a commit message. GStreamer developers generally use 'pluginname: short description of changes', a blank line, and then potentially several lines of detailed information about the changes.

To modify a commit, including adding new files, you can use 'git commit --amend'.

Once you have committed changes, and want to pull new changes from the central GStreamer repository, use 'git pull --rebase'. The '--rebase' option causes git to replay your changes on top of any changes that you pull from the central repository.

To create a nicely formatted patch from the most recent commit, use: 

$ git format-patch -n1

Attaching a patch that is in this form to a bugzilla bug makes applying and merging the patch much easier for another developers that reviews your patch.

If you haven't used git before, it would be a good idea to tell it who you are: 

$ git config --global user.name "George S. Treamer"
$ git config --global user.email "gstreamer@gmail.com"

What to do after you have submitted your patch

Most of all, please be patient. We try to review patches as quickly as possible, but there is such a high turnaround of bugs, patches and feature requests that it is not always possible to tend to them all as quickly as we'd like. This is especially true for completely new plugins. If you haven't gotten any response at all for a while, feel free to 'ping' us by posting a quick follow-up comment to the bug or finding us on IRC (many developers actively track changes in bugzilla via e-mail, so a follow-up comment will usually be noticed).