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.
  • Bump sonames.
  • Update NEWS.
  • Tag the last commit locally (don't make the tag public yet).
  • Generate the tarball.
  • Test the tarball.
  • Upload the tarball.
  • Push the tag.
  • Add git shortlog to the release notes. Proofreading the release notes at this point is a good idea too.
  • If the release notes are marked as a draft, remove that marking.
  • Announce the release on the mailing list.
  • Add a news item to the web site front page.
  • Update the channel topic in IRC.
  • Refresh the online Doxygen documentation.
  • Rebase and push the contents from the "next" branch to "master".
  • 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 v4.0..master -- pulse/cdecl.h pulse/channelmap.h pulse/context.h pulse/def.h pulse/error.h pulse/ext-device-manager.h pulse/ext-device-restore.h pulse/ext-stream-restore.h pulse/format.h pulse/gccmacro.h pulse/introspect.h pulse/mainloop-api.h pulse/mainloop-signal.h pulse/mainloop.h pulse/operation.h pulse/proplist.h pulse/pulseaudio.h pulse/rtclock.h pulse/sample.h pulse/scache.h pulse/simple.h pulse/stream.h pulse/subscribe.h pulse/thread-mainloop.h pulse/timeval.h pulse/utf8.h pulse/util.h pulse/volume.h pulse/xmalloc.h pulse/glib-mainloop.h

Before running that command, change "v4.0" to point to the last released version, and check if there are any new headers added to pulseinclude_HEADERS in Makefile.am. If there are new headers, please update this wiki page.

The command needs to be run in the src directory, because I didn't bother prefixing the files with "src/" when I copied them from pulseinclude_HEADERS.

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.

For your convenience, below are commands for viewing the library changes. Replace "v4.0" with the last released version, and if there are new files added to the libraries, update this wiki page.


git diff v4.0..master -- pulse/cdecl.h pulse/channelmap.c pulse/channelmap.h pulse/context.c pulse/context.h pulse/def.h pulse/error.c pulse/error.h pulse/ext-device-manager.c pulse/ext-device-manager.h pulse/ext-device-restore.c pulse/ext-device-restore.h pulse/ext-stream-restore.c pulse/ext-stream-restore.h pulse/format.c pulse/format.h pulse/gccmacro.h pulse/internal.h pulse/introspect.c pulse/introspect.h pulse/mainloop-api.c pulse/mainloop-api.h pulse/mainloop-signal.c pulse/mainloop-signal.h pulse/mainloop.c pulse/mainloop.h pulse/operation.c pulse/operation.h pulse/proplist.c pulse/proplist.h pulse/pulseaudio.h pulse/rtclock.c pulse/rtclock.h pulse/sample.c pulse/sample.h pulse/scache.c pulse/scache.h pulse/stream.c pulse/stream.h pulse/subscribe.c pulse/subscribe.h pulse/thread-mainloop.c pulse/thread-mainloop.h pulse/timeval.c pulse/timeval.h pulse/utf8.c pulse/utf8.h pulse/util.c pulse/util.h pulse/volume.c pulse/volume.h pulse/xmalloc.c pulse/xmalloc.h


git diff v4.0..master -- pulse/simple.c pulse/simple.h


git diff v4.0..master -- pulse/glib-mainloop.h pulse/glib-mainloop.c


Create a signed tag:

git tag -s -m "PulseAudio 4.99.1" v4.99.1 master

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

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:

md5sum pulseaudio-4.99.1.tar.gz > pulseaudio-4.99.1.tar.gz.md5
sha1sum pulseaudio-4.99.1.tar.gz > pulseaudio-4.99.1.tar.gz.sha1
md5sum pulseaudio-4.99.1.tar.xz > pulseaudio-4.99.1.tar.xz.md5
sha1sum pulseaudio-4.99.1.tar.xz > pulseaudio-4.99.1.tar.xz.sha1

Uploading the Tarball

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

Updating the Topic in IRC

/msg ChanServ topic #pulseaudio new topic here

Refreshing the online Doxygen documentation

make doxygen
scp doxygen/html/* annarchy.freedesktop.org:/srv/www.freedesktop.org/www/software/pulseaudio/doxygen