Maintainer Documentation

Making Releases


  • Fix all release blocker bugs.
  • Check the bug list in case there's still some bug that should be a release blocker.
  • As a smoke test, run the current git master version on your own machine for a while.
  • Check that the "since" tags in the Doxygen documentation are correct.
  • Update the Bluetooth wiki page.
  • Bump sonames.
  • (final release only) Update NEWS.
  • Tag the last commit locally (don't make the tag public yet).
  • Generate the tarball.
  • Check that all new files are included in the tarball.
  • Test the tarball.
  • Upload the tarball.
  • Push the tag.
  • (final release only) Add git shortlog to the release notes. Proofreading the release notes at this point is a good idea too.
  • (final release only) If the release notes are marked as a draft, remove that marking.
  • Announce the release on the mailing list.
  • (final release only) Add a news item to the web site front page.
  • Update the channel topic in IRC.
  • (final release only) Refresh the online Doxygen documentation.
  • (final release only) Rebase and push the contents from the "next" branch to "master".
  • (final release only) Close the old release blocker tracker bug and create another.

Checking the "since" Tags in the Doxygen Documentation

It's relatively easy to forget to add the "since" tags in the Doxygen documentation, or to have a wrong version in them (for example, a patch is submitted that is targeted for 4.0, but it ends up merged during the 5.0 cycle). It's pretty easy to check that the tags are correct by diffing the public headers since the last release.

git diff v5.0..master -- src/pulse/*.h

Before running that command, change "v5.0" to point to the last released version.

Bumping Sonames

We have currently three public API libraries: libpulse, libpulse-simple and libpulse-mainloop-glib (if new ones have been added, please update this wiki page). The "sonames" of those libraries need to be bumped before each release (release candidates are releases too in this context). The soname versions are defined in configure.ac. The definitions for v4.0 look as follows:




Rules for bumping "X:Y:Z":

  • If there are backwards incompatible changes to the library binary interface, something went wrong. We don't break the ABIs.
  • If there are backwards compatible changes to the library binary interface, increment X and Z by one, and set Y to zero.
  • If there are no interface changes, but there are changes to the implementation, increment Y by one.
  • If there are no changes at all in the library, don't touch the version.

Library changes can be found easily by viewing only changes that affect files under src/pulse. For example:

gitk v7.0...master -- src/pulse


Create a signed tag:

git tag -s -m "PulseAudio 4.99.1" v4.99.1 master
git clean -xdf   # Beware, this will wipe everything that isn't stored in git!

You'll need to have a GPG key with the default e-mail address configured in git.

The clean command is needed, because otherwise the tarball will have wrong version in its file name (and quite possibly the wrong version will appear elsewhere too). The version number is cached somewhere, and even rerunning ./configure doesn't update it.

When it's time to push the tag (after generating the tarball and testing that it works), this is the command:

git push origin v4.99.1

Generating the Tarball

make distcheck

That will create a .tar.gz file and a .tar.xz file. Then you'll need to create matching checksum files too:

for i in pulseaudio-*.tar.*z; do \
  md5sum ${i} > ${i}.md5;        \
  sha1sum ${i} > ${i}.sha1;      \

Checking that all new files are included in the tarball

git ls-files > /tmp/file-list-new              # Generate the file list for the new release
git checkout v10.0                             # Check out the previous release
git ls-files > /tmp/file-list-old              # Generate the file list for the previous release
diff -u /tmp/file-list-old /tmp/file-list-new  # Compare the file lists

Check what files have been added. Are they all included in the tarball?

Uploading the Tarball

scp pulseaudio-*.tar.* annarchy.freedesktop.org:/srv/www.freedesktop.org/www/software/pulseaudio/releases


/msg ChanServ topic #pulseaudio new topic here

And don't forget to update the news section of http://www.freedesktop.org/wiki/Software/PulseAudio

Refreshing the online Doxygen documentation

make doxygen
rsync -av --delete-after doxygen/html/ annarchy.freedesktop.org:/srv/www.freedesktop.org/www/software/pulseaudio/doxygen/

After uploading, check that all files have these permissions set:


There was once some trouble with missing group write access with newly created files.