CvsCommitGuidelines

Guidelines for GStreamer developers with CVS commit access

This is a draft and by no means complete. In fact, it's not even a draft, it's just a bunch of bullet points.

Committing

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 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 ChangeLog when adding new API (ie. exported functions, GObject vfuncs, GObject properties or GObject signals), e.g.: 

2010-10-10  You <you@youdot.com>

        * gst/gstutils.c: (gst_utils_foo)
        * gst/gstutils.h:
          API: gst_utils_foo()

or 

2010-10-10  You <you@youdot.com>

        * plugins/elements/gstfakesrc.c: (gst_fake_src_class_init),
        (gst_fake_src_init), (gst_fake_src_set_property),
        (gst_fake_src_get_property), (gst_fake_src_start):
        * plugins/elements/gstfakesrc.h:
        Added format property to control the format of the newsegment events.
        API: GstFakeSrc:format

(There is not exact format, just make sure to use the keyword)

Tools

moap: maintainer of a project

Tries, among other things, to unify things like prepare-ChangeLog.pl and cicl in one single program and interface, and to make it work for all the different revision control systems out there (CVS, SVN, git, etc.).

moap is still a bit fiddly to set up, and could use some changes to make the ChangeLog output with exuberant-ctags look decent, but it's nice to work with once you've set it up right. The typical workflow would be: 

Create a ChangeLog entry with all changes:
$ moap cl prep
Updating ChangeLog from CVS repository.
Finding changes.
Extracting affected tags from source.
Editing ChangeLog.
Trim the ChangeLog entry to what you want to commit, and add explanation of the changes:
$ vim ChangeLog
Double-check the changes to commit:
$ moap cl diff | more
Finally, commit:
$ moap cl ci

old skool: prepare-ChangeLog.pl, diffcl, cicl

There are multiple versions of the prepare-ChangeLog.pl script and the cicl script around, some with support for different revision control systems and the like. Here is one version of these scripts:

setting up your name and e-mail address

Both of these tools expect you to set your CHANGE_LOG_EMAIL_ADDRESS and CHANGE_LOG_NAME environment variable to your e-mail address and name respectively. You can do that by adding something like this to either your ~/.bashrc or ~/.bash_profile file: 

# for prepare-ChangeLog.pl and moap cl prep
export CHANGE_LOG_EMAIL_ADDRESS="macgyver at somedomain dot com"
export CHANGE_LOG_NAME="John MacGyver "

Random notes