GitDeveloperGuidelines

Guidelines for GStreamer developers

Best practices and git use guidelines for GStreamer developers and contributors

This document is a draft and by no means complete. If in doubt, ask in the IRC channel.

Committing

Remote branches

Merging branches

git checkout branch
git rebase master
git checkout master
git merge branch 

checkout master
merge branch
rebase origin/master

You might also want to use git pull --rebase instead of git pull when you update.

Pushing changes

Committing changes that deprecate API

see DeprecatingAPI for details

Adding new API

New API covers things such as:

Generally, new API should be reviewed before being committed, especially new core or core/-base libs API (in practice you'll find that there is a bit of a gray area here and the rule does not always apply to module maintainers or lead developers).

Getting your new API reviewed is best done by filing an enhancement bug against the module in question and attaching a patch which adds the new API and includes a gtk-doc blurb (don't forget the 'Since: 0.10.x' at the end of the gtk-doc blurb and adding your new function to the appropriate -sections.txt file in the docs/ directory). Mark the bug summary with the [API] keyword for extra attention. Then either wait until you get feedback, or poke people on IRC to have a look at it. If you don't get feedback, keep poking. Don't assume it's ok to commit/push new API just because no one raised any objections.

Some simple unit tests for the new API are always a good thing too.

Adding properties

If you're adding new properties, please add a gtk-doc chunk with a 'Since:' tag for the property, e.g. 

  /**
   * GstPipeline:delay
   *
   * The expected delay needed for elements to spin up to the
   * PLAYING state expressed in nanoseconds.
   * see gst_pipeline_set_delay() for more information on this option.
   *
   * Since: 0.10.5
   **/
  g_object_class_install_property (gobject_class, PROP_DELAY,
      g_param_spec_uint64 ("delay", "Delay",
          "Expected delay needed for elements "
          "to spin up to PLAYING in nanoseconds", 0, G_MAXUINT64, DEFAULT_DELAY,
          G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));

Committing new API

Use the 'API:' keyword in the body of the commit message when adding new API (ie. exported functions, GObject vfuncs, GObject properties or GObject signals), e.g.: 

Add API to intercept flow returns.

...extensive description...

API: gst_pad_add_flow_probe()

or 

fakesrc: add format property to control the format of the newsegment events.

API: GstFakeSrc:format

(There is not exact format for this stuff, just make sure to use the keyword to make life easier for the release manager)

Tools

We don't maintain a ChangeLog file in git any longer, but auto-generate it upon release from the git commit messages. Therefore it is no longer necessary to use tools like moap, prepare-ChangeLog.pl or cicl

setting up your name and e-mail address

$ git config --global user.name "FirstName LastName"
$ git config --global user.email "user@example.com"

See the Git Guide for more setup options (colours etc.)

Personal repositories

Explanations available here for creating a personal repository on freedesktop.org (if you have an account there) : http://www.freedesktop.org/wiki/Infrastructure/git/RepositoryAdmin

There are many other git hosting facilities out there if you don't have a freedesktop.org account (github.org and gitorious.org for example).

Once you have created a personal repository, you can locally add that repository to the list of remote repositories your local checkout is tracking (let's say we created a personal repo for storing our work branches for work on gstreamer core): 

$ me@local> cd gstreamer.git
$ me@local> git remote add myrepo ssh://people.freedesktop.org/~username/gstreamer

If you have a local work branch (called 'mywork') you can now push it to your personal repository 

$ me@local> git push myrepo mywork:mywork

Random notes

Also see