campaign: Change video of the day to John Pershing (1010data)
[gnupg-doc.git] / web / devel / creating-a-release.org
1 #+TITLE: GnuPG Hacking - Creating a Release
2 #+STARTUP: showall indent
3 #+SETUPFILE: "share/setup.inc"
4
5 * Creating a Release
6
7 This is a description of the steps necessary to build a software
8 release of GnuPG and related software.
9
10
11 ** Overview of the Build System
12
13 FIXME
14
15 ** Stuff required
16
17 A Unix system, preferable Debian because that is what we use for our
18 development.
19
20
21 ** Release Planning
22
23 If you are planning a new release and strings have changed you should
24 send a notification to all translators, so that they have time to
25 update their translations.  The script ~build-aux/mail-to-translators~
26 in the gnupg-repo might be useful for this.  You need to edit it to
27 actually send out something.
28
29 ** Step by Step
30
31 *** Make sure that all new PO files are checked in.
32
33 *** Decide whether you want to update the automake standard files
34
35 These are mainly the files ~config.guess~ and ~config.sub~.  In
36 general these files should be the same for all package.  Do not update
37 them for each release because having consistent files in all packages
38 can avoid bug reports due to different cpu-vendor-os strings
39
40 Commit these changes.
41
42 *** Update the translation files
43
44 Run:
45
46 :  make -C po update-po
47
48 This merges the latest changes into the po files and disable entries
49 which do not anymore match.  The latter is important for example to
50 avoid mismatches in printf format strings.
51
52 You should then commit the changes using a subject of "po: Auto
53 update".
54
55 *** Update the LT version
56
57 This affects only library packages.  The libtool version (LT version)
58 is updated only right before a release.  The configure.ac file has
59 comments on how to update them.  Note that libraries which come with
60 language bindings may have several independent LT version.
61
62 FIXME: Describe why and how they are to be updated.
63
64 *** Write NEWS entries
65
66 Remember to set the release date in the NEWS file.  For libraries it
67 is suggested to note the LT version as well.  Use the format
68 "Cz/Ay/Rz" to give the Current/Age/Release numbers.
69
70 *** Check README and doc files
71
72 You may for example want to update the version information and make
73 sure that they still have correct information.  Files you should look
74 at are for example:
75
76 - README
77 - AUTHORS
78 - src/versioninfo.rc.in (Windows)
79
80 *** Commit all changes with a subject of "Release m.n.o."
81
82 This is the final commit which has all changes for the version.
83
84 Do not push this commit.
85
86 *** Create a signed tag with the name "foo-m.n.o".
87
88 The git tag needs to be signed.  We use hardware tokens to hold the
89 signing key.  The command to do this is
90
91 : git tag -u KEYID foo-m.n.o
92
93 You will be asked for a message.  Put a funny message or better the
94 main feature of this release into the commit log message.
95
96 Do not push this tag.
97
98 In case you need to restart the release process, you should first
99 remove the tag (=git tag -d foo-m.n.o=) and then also revert the last
100 commit.
101
102 *** Recreate the configure script
103
104 : ./autogen.sh --force
105
106 The option =--force= is required for the git magic in configure.ac to
107 work properly.
108
109 This calls autoconf and automake and does some M4 magic to encode the
110 the version number and information from Git into the new configure
111 script.  Note that the created =configure= script may not be tracked
112 by Git.
113
114 *** Build a release tarball
115
116 This is easy:
117
118  : ./configure --enable-maintainer-mode
119
120  : make distcheck
121
122 it is suggested to run the latter inside Emacs so that the compile log
123 can be viewed for errors.
124
125 FIXME: Explain why and how to use a VPATH build.
126
127 *** Build and test the release
128
129 This is best done on a different machine.  Make sure to also build the
130 Windows version so that you won't run into a surprise when building a
131 Windows versions later.
132
133 Keep a test build available for later.
134
135
136
137 *** Sign the tarball
138
139 Also store the created .swdb file away.
140
141 *** Copy the tarball to a staging area
142
143 *** Update the webpages
144
145 At least the file swdb.mac needs an update.  This is done using the
146 saved swdb.
147
148 *** Prepare for the next release
149
150  - Add a new headline to NEWS.
151
152  - Bump the version number in configure.ac up (Do not bump the LT
153    version, though)
154
155  - Commit with a subject "Post release updates" or similar.
156
157 *** Push all changes
158
159 Do not forget to push also the tags.
160
161 In case you run into a conflict you need to start from scratch.  That
162 is removing the last two commits from your local copy, removing the
163 tag, merge the changes, and to to the first step.  Make sure that the
164 version and LT version numbers are correct for the second try.  To
165 avoid this problem it is often better to work on a release branch and
166 later merge the changes back to master.
167
168 *** Copy the files from the staging area to the FTP server
169
170 *** Update the online docs
171
172 Using the final test build run a "make -C doc online".
173
174 *** Write an announcement.
175
176
177 ** Notes on some packages
178
179 Here are some gotchas for certain packages
180
181 *** GnuPG
182
183 - Check that https://savannah.gnu.org/projects/gnupg  is up to date.
184   This is a simple page which merely points to gnupg.org, though.
185
186
187 *** GnuPG Windows Installer
188
189 To build a GnuPG >= 2.1 installer you need to change to a working
190 directory, for example:
191
192 : cd ~/b-w32/speedo
193
194 then cleanup and unpack the GnuPG source:
195
196 : rm -r PLAY PLAY-release
197 : tar xjf /foo/bar/gnupg-m.n.o.tar.gz
198
199 run a script which does about everything:
200
201 : make -f gnupg-m.n.o/build-aux/speedo.mk w32-release
202
203 finally you should sign the created installer using:
204
205 : make -f gnupg-m.n.o/build-aux/speedo.mk w32-sign-installer
206
207 and also sign them using your release key:
208
209 : gpg -sbvu MYKEY gnupg-w32-m.n.o_YYYYMMDD.tar.xz
210 : gpg -sbvu MYKEY gnupg-w32-m.n.o_YYYYMMDD.exe
211
212 You will end up with these files:
213
214  - gnupg-w32-m.n.o_YYYYMMDD.tar.xz
215  - gnupg-w32-m.n.o_YYYYMMDD.tar.xz.sig
216  - gnupg-w32-m.n.o_YYYYMMDD.exe
217  - gnupg-w32-m.n.o_YYYYMMDD.exe.sig
218  - gnupg-w32-m.n.o_YYYYMMDD.exe.swdb
219
220 Use the swdb file to update the swdb.mac and distribute tye other
221 files (after testing).
222
223
224 *** Libgcrypt
225
226 *** GPGME
227
228 - As of version 1.9 build problems in "make distcheck" for the Python
229   bindings may turn up.  The workaround is to use a fresh build
230   directory.
231
232
233
234
235 ** Pitfalls
236
237 Sometimes you may run into problems without seeing the actual
238 problem.  Here is a list of such things
239
240 *** Permission problem moving "xx.new.po" to "xx.po"
241
242 If during "make distcheck" you get an error about a permission problem
243 moving foo.new.po to foo.po; this is caused by a check whether the po
244 files can be re-created.  Now if the first tarball has been created in
245 a different top directory and if there exists a no distributed file
246 with the string "GNU gnupg" (e.g. a log file from running make) you
247 end up with different comments in the po files.  Check out
248 /usr/lib/gettext/project-id for that silliness.  As a hack we added
249 this string into configure.ac.