summaryrefslogtreecommitdiff
path: root/Software/PulseAudio/Documentation/Maintainer.mdwn
blob: ac4b2f5ddef5e93446e381bc5205d4b5f6411e49 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
[[!inline pages="Software/PulseAudio/Style1" quick="yes" raw="yes"]]
[[!meta title="Modules – PulseAudio"]]
[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]]
# Maintainer documentation
[[!toc levels=2]]

---
# Release checklist

: **Fix all release blocker bugs**<br>
: **Check the bug list in case there's still some bug that should be a release blocker**<br>
: **As a smoke test, run the current git master version on your own machine for a while**<br>
: **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|Software/PulseAudio/Documentation/User/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:

    AC_SUBST(LIBPULSE_VERSION_INFO, [16:2:16])

    AC_SUBST(LIBPULSE_SIMPLE_VERSION_INFO, [0:4:0])

    AC_SUBST(LIBPULSE_MAINLOOP_GLIB_VERSION_INFO, [0:4:0])

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 v14.0..HEAD | cut -f2

---
## (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

    meson dist -C build --formats=gztar,xztar

That will create a .tar.gz file and a .tar.xz file and corresponding checksum files in build/meson-dist.

### paprefs

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;  \
    done

---
## 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

### pulseaudio

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

### pavucontrol

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

### paprefs

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

---
## Push the tag

    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

### pavucontrol

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

### paprefs

    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: 14.2 || Troubleshooting: https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/Users/Troubleshooting/ || The channel is logged: https://freenode.logbot.info/pulseaudio

---
## (final release only) Refresh the online Doxygen documentation

    ninja -C build doxygen
    rsync -av --delete-after build/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