Submitting Patches

Where

Please submit patches for GStreamer in GNOME bugzilla:

• you will need to create a GNOME bugzilla account if you don't have one yet (yep, that's just how it is, sorry for the inconvenience)
• create a new bug if there is no bug report for this issue yet; This page has shortcuts for the major components
• once you have created a bug you can attach your patch(es), see below for more details
• if your patch is an enhancement or new API, please set your bug's severity to 'enhancement'
• if your patch is against a specific plugin or element, prefix the Summary with [element-name] or [plugin-name] and keep the rest of the description as short and precise as possible. Example: [id3demux] add support for WCOP frame. This makes sure developers looking through the list of open bugs can quickly identify what your bug is about; if your text is too long and only contains fill words at the beginning, the important information will be cut off and not show up in the list view.
• create separate bugs for separate issues 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 submit patches in git format-patch format, as attachement to a bug in bugzilla.

The easiest way to create such patches is to create one or more local commits for your changes in a local git repository. This can be a git clone checkout of the module in question, or you could create a git repository in any directory that has the source code, e.g. the directory created when unpacking the source tarball (using git init, then git add . and git commit -m 'import tarball as initial revision').

Once you have a git repository with the original code in in it, you can make your modifications and create a local commit with e.g. git commit path/to/file1.[ch]. This will pop up an editor where you can create your commit message. It should look like:

exampledemux: fix seeking without index in push mode

Without an index we would refuse to seek in push mode. Make
seeking without an index work by estimating the position
to seek to. It might not be 100% accurate, but better than
nothing.

https://bugzilla.gnome.org/show_bug.cgi?id=987654

Then exit the editor, and you should have a commit.

Check the commit with git show or git log -p.

Make sure the author is correctly set to your full name and e-mail address.

You can make changes to the last commit using:

• git commit --amend to fix up the commit message, or
• git commit --amend --author='John You <john@you.com>' to fix up the author, or
• git add path/to/file1.[ch]; git commit --amend to incorporate fixes made to the files into the last commit Once everything looks fine, create the patch file for the last commit with: git format-patch -1

If you have multiple commits, pass -2, -3, etc.

This should create one or more patch files named 0001-blahblah, 0002-blehblah etc. in the current directory. Attach these to a bug report in bugzilla.

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 (requires GNU indent installed).

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