Maintainer documentation

Release checklist

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

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.

Update the Bluetooth wiki page

The page has a history section detailing what significant bluetooth related changes each version has, so document the bluetooth changes of the new release. Other sections may need updating as well.

Bump 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

(final release only) Update NEWS or README

In case of pavucontrol and paprefs, there's no NEWS file, but you should add a news item to doc/README.html.in.

Git shortlog can be used to generate the contributor list that we add to the entries in NEWS:

git shortlog -s v12.0..master

That command will also show the commit counts, so the output needs some manual editing. TODO: It should be pretty easy to use command line tools to edit the shortlog output so that it's suitable for direct copy-paste, somebody please figure out how to do that and document it here.

(pavucontrol & paprefs) Update the version number in configure.ac or meson.build

Tag the last commit locally (don't make the tag public yet)

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.

Generate the tarball

pulseaudio & pavucontrol

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 *.tar.*z; do \
  sha256sum ${i} > ${i}.sha256;  \


paprefs doesn't have "make distcheck" available since it's using Meson. You can generate the tarball with "git archive". First make sure that you have the tar.xz archiver configured:

git config --global tar.tar.xz.command "xz -c"

Here's the actual archive command (some trickery added to avoid repeating the version number):

VERSION=1.0 bash -c "git archive --prefix=paprefs-\$VERSION/ -o paprefs-\$VERSION.tar.xz v\$VERSION"

If the tar.xz archiver isn't properly configured, the command will silently produce a plain tar archive without compression. Check that the file is actually compressed (the command should print "XZ compressed data"):

file paprefs-*.tar.xz

Checksum generation:

for i in paprefs-*.tar.xz; do \
  sha256sum ${i} > ${i}.sha256;  \

Check 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?

Test the tarball

Upload the tarball


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


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


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

Push the tag

git push origin master
git push origin v4.99.1

(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

(pavucontrol & paprefs) Upload README.html


scp doc/README.html annarchy.freedesktop.org:/srv/www.freedesktop.org/www/software/pulseaudio/pavucontrol/


scp build/doc/README.html annarchy.freedesktop.org:/srv/www.freedesktop.org/www/software/pulseaudio/paprefs/

Update the channel topic in IRC

/msg ChanServ topic #pulseaudio Stable release: 12.2 || Release candidate 1 for 13.0 is out now, please test! || Planet: https://freedesktop.org/software/pulseaudio/planet

(final release only) Refresh the online Doxygen documentation

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

(final release only) Rebase and push the contents from the "next" branch to "master"

Remove the "next" branch afterwards.

(final release only) Close the old release blocker tracker bug and create another