1 Instructions to create pretest or release tarballs. -*- coding: utf-8 -*-
2 -- originally written by Gerd Moellmann, amended by Francesco Potortì
3 with the initial help of Eli Zaretskii
6 Steps to take before starting on the first pretest in any release sequence:
8 0. The release branch (e.g. emacs-28) should already have been made
9 and you should use it for all that follows. Diffs from this
10 branch should be going to the emacs-diffs mailing list.
12 1. Decide on versions of m4 and autoconf, and ensure you will
13 have them available for the duration of the release process.
15 2. Consider increasing the value of the variable
16 'customize-changed-options-previous-release' in cus-edit.el to
17 refer to a newer version of Emacs. (This is now done when cutting
18 the release branch, see admin/release-branch.txt, but it can't
19 hurt to double check its value.) Commit cus-edit.el if changed.
21 3. Remove any old pretests from https://alpha.gnu.org/gnu/emacs/pretest.
22 You can use 'gnupload --delete' (see below for more gnupload details).
23 (We currently don't bother with this.)
25 4. Check that all new Lisp libraries belong to sensible packages.
26 Run "make -C lisp finder-data" and check the diff of the generated
27 file against the previously released Emacs version to see what has
30 5. If this is an emergency release without a prior pretest, inform the
31 maintainers of the bundled packages which are developed separately
32 to make sure they install adjustments required for an official
33 release. Currently, these packages include:
37 General steps (for each step, check for possible errors):
39 1. git pull # fetch from the repository
40 git status # check for locally modified files
42 Ensure that you have a clean, unmodified state.
43 If you switched in-place from another branch to the release branch,
44 there could be inappropriate generated ignored files left over.
45 You might want to use "git status --ignored" to check for such files,
46 or some form of "git clean -x". It's probably simpler and safer to
47 make a new working directory exclusively for the release branch.
49 If the working directory has subdirectories created when making
50 previous releases or pretests, remove those subdirectories, as the
51 command which updates the ChangeLog file might attempt to recurse
52 there and scan any ChangeLog.* files there.
54 Make sure the tree is built, or at least configured. That's
55 because some of the commands below run Make, so they need
56 Makefiles to be present.
58 For Emacs 28 and later, as long as --with-native-compilation is
59 not the default, the tree needs to be configured with
60 native-compilation enabled, to ensure all the pertinent *.elc
61 files will end up in the tarball. Otherwise, the *.eln files
62 might not build correctly on the user's system.
65 ./configure --with-native-compilation && make
67 For a release (as opposed to pretest), visit etc/NEWS and use the
68 "M-x emacs-news-delete-temporary-markers" command to delete any
69 left-over "---" and "+++" markers from etc/NEWS, as well as the
70 "Temporary note" section at the beginning of that file, and commit
71 etc/NEWS if it was modified. For a bug fix release (e.g. 28.2),
72 delete any empty headlines too.
74 2. Regenerate the versioned ChangeLog.N and etc/AUTHORS files.
76 The "M-x authors" command below will first update the current
77 versioned ChangeLog.N file. For this to work correctly, make sure
78 the top-level Makefile says
80 PREFERRED_BRANCH = emacs-NN
82 where NN is the version on the release branch from which you are
83 producing the tarball. If NN is incorrect (which it usually is
84 when starting a pretest of a new major release), update
85 Makefile.in and re-run 'configure' to update Makefile.
87 For the first pretest of a new major release, consider starting a
88 new top-level ChangeLog.N file if the last versioned ChangeLog.N
89 file is too large. A good point to start a new ChangeLog.N file
90 is when the last one gets larger than 5 MiB, or when you make the
91 first pretest of a new major release, whichever happens later. If
92 so, start a new ChangeLog.N file by bumping N, and also update the
93 line in top-level Makefile.in which says
95 CHANGELOG_HISTORY_INDEX_MAX = N
97 by incrementing the value of N by 1; then regenerate Makefile.
98 After bumping N, you need to actually create and commit
99 ChangeLog.N with the updated N, otherwise "M-x authors" below will
100 fail. The easiest way of creating the new ChangeLog.N is to
101 rename the file ChangeLog (without the .N suffix) left over from
102 the last major release (it is usually unversioned) and commit it.
106 M-: (require 'authors) RET
109 If this says "Problem updating ChangeLog", find the reason for the
110 failure of the command it runs, viz.:
112 make -C ROOT change-history-nocommit
114 (where ROOT is the top-level directory where you run this). It
115 could be because there are uncommitted changes in ChangeLog.N, for
116 example. One possible way forward is to invoke "C-u M-x authors",
117 which will skip updating the versioned ChangeLog.N file.
119 After "M-x authors" finishes, if there is an "*Authors Errors*"
120 buffer, address the issues. If there was a ChangeLog typo, fix
121 the relevant entry. If a file was deleted or renamed, consider
122 adding an appropriate entry to variables authors-ignored-files,
123 authors-valid-file-names, or authors-renamed-files-alist in
124 authors.el. If some authors are "ignored", consider adding
125 entries to the author-aliases variable.
127 If necessary, repeat 'C-u M-x authors' after making those changes.
128 Save the "*Authors*" buffer as etc/AUTHORS.
129 Check the diff looks reasonable. Maybe add more entries to
130 authors-ambiguous-files or authors-aliases, and repeat.
131 Commit any fixes to authors.el.
133 3. Set the version number (M-x load-file RET admin/admin.el RET, then
134 M-x set-version RET). For a pretest, start at version .90. After
135 .99, use .990 (so that it sorts). Commit the resulting changes
136 as one, with nothing else included, and using a log message
137 of the format "Bump Emacs version to ...", so that the commit can
138 be skipped when merging branches (see admin/gitmerge.el).
140 The final pretest should be a release candidate.
141 Before a release candidate is made, the tasks listed in
142 admin/release-process must be completed.
144 Set the version number to that of the actual release (commit in
145 one, as described above). Pick a date about a week from now when
146 you intend to make the release. Use M-x add-release-logs from
147 admin/admin.el to add entries to etc/HISTORY and the ChangeLog
148 file. It's best not to commit these files until the release is
149 actually made. Merge the entries from (unversioned) ChangeLog
150 into the top of the current versioned ChangeLog.N and commit that
151 along with etc/HISTORY. Then you can tag that commit as the
154 Alternatively, you can commit and tag with the RC tag right away,
155 and delay the final tagging until you actually decide to make a
156 release and announce it. The "git tag" command can tag a specific
157 commit if you give it the SHA1 of that commit, even if additional
158 commits have been pushed in the meantime.
160 Name the tar file as emacs-XX.Y-rc1.tar. If all goes well in the
161 following week, you can simply rename the file and use it for the
162 actual release. If you need another release candidate, remember
163 to adjust the ChangeLog and etc/HISTORY entries.
165 If you need to change only a file(s) that cannot possibly affect
166 the build (README, ChangeLog, NEWS, etc.) then rather than doing
167 an entirely new build, it is better to unpack the existing
168 tarfile, modify the file(s), and tar it back up again.
170 Never replace an existing tarfile! If you need to fix something,
171 always upload it with a different name.
173 4. autoreconf -i -I m4 --force
176 The below script checks for any mistakes in the source text of
177 manual pages. Fix any errors and re-run the script to verify.
179 ./admin/check-man-pages
184 make -C etc/refcards clean
186 If some of the etc/refcards, especially the non-English ones, fail
187 to build, you probably need to install some TeX/LaTeX packages, in
188 particular for foreign language support. For more information,
189 search for the string "refcard" in the file admin/release-process.
191 (ru-refcard causes numerous "Underfull hbox" and "Overfull hbox"
192 messages from TeX, but those seem to be harmless, as the result
195 5. Copy lisp/loaddefs.el to lisp/ldefs-boot.el. After copying, edit
198 ;; no-byte-compile: t
200 to its file-local variables section, otherwise make-dist will
203 Commit ChangeLog.N, etc/AUTHORS, lisp/ldefs-boot.el, and the files
204 changed by M-x set-version. Note that the set-version changes
205 should be committed separately, as described in step 3 above, to
206 avoid them being merged to master. The lisp/ldefs-boot.el file
207 should not be merged to master either, so it could be added to the
208 same commit or committed separately.
210 The easiest way of doing that is "C-x v d ROOT-DIR RET", then go
211 to the first modified file, press 'M' to mark all modified files,
212 and finally 'v' to commit them. Make sure the commit log message
213 mentions all the changes in all modified files, as by default 'v'
214 doesn't necessarily do so.
216 If someone else made a commit between step 1 and now,
217 you need to repeat from step 4 onwards. (You can commit the files
218 from step 2 and 3 earlier to reduce the chance of this.)
220 6. If there has been a change in who is the Emacs maintainer since
221 the last release, update doc/misc/ack.texi and admin/MAINTAINERS
222 to reflect this. You can commit this separately.
224 7. ./make-dist --snapshot --no-compress
226 Check the contents of the new tar with admin/diff-tar-files
227 against the previous release (if this is the first pretest) or the
228 previous pretest. If you did not make the previous pretest
229 yourself, find it at <https://alpha.gnu.org/gnu/emacs/pretest>.
230 Releases are of course at <https://ftp.gnu.org/pub/gnu/emacs/>.
232 ./admin/diff-tar-files emacs-OLD.tar emacs-NEW.tar
234 Alternatively, if you want to use the compressed tarballs (which
235 diff-tar-files doesn't understand):
237 tar tJf emacs-OLD.tar.xz | sed -e 's,^[^/]*,,' | sort > old_tmp
238 tar tJf emacs-NEW.tar.xz | sed -e 's,^[^/]*,,' | sort > new_tmp
239 diff -u old_tmp new_tmp
241 If this is the first pretest of a major release, just comparing
242 with the previous release may overlook many new files. You can try
243 something like 'find . | sort' in a clean repository, and
244 compare the results against the new tar contents. Another
245 alternative is using something like:
247 tar cf - emacs-NEW | tar t -C /tmp | grep -Ev "\.(o|d)$" | sort
249 Where emacs-NEW is the directory containing your clean repository.
250 The output of this command might be easier to compare to the
251 tarball than the one you get from find.
253 8. tar xf emacs-NEW.tar; cd emacs-NEW
254 ./configure --prefix=/tmp/emacs && make check && make install
256 Use 'script' or M-x compile to save the compilation log in
257 compile-NEW.log and compare it against an old one. The easiest way
258 to do that is to visit the old log in Emacs, change the version
259 number of the old Emacs to __, do the same with the new log and do
260 M-x ediff. Especially check that Info files aren't built, and that
261 no autotools (autoconf etc) run.
263 9. You can now tag the release/pretest and push it together with the
266 cd EMACS_ROOT_DIR && git tag -a TAG -m "Emacs TAG"
270 Here TAG is emacs-XX.Y.ZZ for a pretest, emacs-XX.Y for a release.
271 For a release, if you are producing a release candidate first, use
272 emacs-XX.Y-rcN (N = 1, 2, ...) when you tar the RC, and add the
273 actual release tag later, when the official release tarball is
274 uploaded to ftp.gnu.org. When adding a tag later, it is safer to
275 use the SHA1 of the last commit which went into the release
276 tarball, in case there were some intervening commits since then:
278 git tag -a TAG -m "Emacs TAG" SHA1
281 In the past, we were not always consistent with the annotation
282 (i.e. -m "Emacs TAG"). The preferred format is like this for a
283 pretest, release candidate and final release:
285 git tag -a emacs-28.0.90 -m "Emacs 28.0.90 pretest"
286 git tag -a emacs-28.1-rc1 -m "Emacs 28.1 RC1"
287 git tag -a emacs-28.1 -m "Emacs 28.1 release"
289 10. Decide what compression schemes to offer.
290 For a release, at least gz and xz:
291 gzip --best --no-name -c emacs-NEW.tar > emacs-NEW.tar.gz
292 xz -c emacs-NEW.tar > emacs-NEW.tar.xz
293 For pretests, just xz is probably fine (saves bandwidth).
295 Now you should upload the files to the GNU ftp server. In order to
296 do that, you must be registered as an Emacs maintainer and have your
297 GPG key acknowledged by the ftp people. For instructions, see
298 https://www.gnu.org/prep/maintain/html_node/Automated-Upload-Registration.html
299 The simplest method to upload is to use the gnulib
300 <https://www.gnu.org/s/gnulib/> script "build-aux/gnupload":
303 gnupload [--user your@gpg.key.email] --to alpha.gnu.org:emacs/pretest \
307 gnupload [--user your@gpg.key.email] --to ftp.gnu.org:emacs \
310 You only need the --user part if you have multiple GPG keys and do
311 not want to use the default. Instead of "your@gpg.key.email" you
312 could also use the fingerprint of the key, a 40-digit hex number.
313 (Alternatively, define default-key in your ~/.gnupg/gpg.conf file.)
314 Obviously, if you do not have a fast uplink, be prepared for the
315 upload to take a while.
318 If you prefer to do it yourself rather than use gnupload:
320 For each FILE, create a detached GPG binary signature and a
321 clearsigned directive file like this:
324 echo directory: emacs/pretest > FILE.directive (for a pretest)
325 echo directory: emacs > FILE.directive (for a release)
326 gpg --clearsign FILE.directive
327 Upload by anonymous ftp to ftp://ftp-upload.gnu.org/ the files FILE,
328 FILE.sig, FILE.directive.asc.
329 For a release, place the files in the /incoming/ftp directory.
330 For a pretest, place the files in /incoming/alpha instead, so that
331 they appear on https://alpha.gnu.org/.
333 11. After five minutes, verify that the files are visible at
334 https://alpha.gnu.org/gnu/emacs/pretest/ for a pretest, or
335 https://ftp.gnu.org/gnu/emacs/ for a release.
337 Download them and check the signatures and SHA1/SHA256 checksums.
338 Check they build (./configure --with-native-compilation).
340 12. Send an announcement to: emacs-devel, and bcc: info-gnu-emacs@gnu.org.
341 For a pretest, also bcc: platform-testers@gnu.org.
342 For a release, also bcc: info-gnu@gnu.org.
343 (The reason for using bcc: is to make it less likely that people
344 will followup on the wrong list.)
345 See the info-gnu-emacs mailing list archives for the form
346 of past announcements. The first pretest announcement, and the
347 release announcement, should have more detail.
348 Use the emacs-devel topic 'emacs-announce'. The best way to do
349 this is to add a header "Keywords: emacs-announce" to your mail.
350 (You can also put it in the Subject, but this is not as good
351 because replies that invariably are not announcements also get
352 sent out as if they were.)
354 To create the included SHA1 and SHA256 checksums, run:
356 sha1sum emacs-NEW.tar.xz
357 sha256sum emacs-NEW.tar.xz
359 You can optionally sign the announcement email, preferably using
360 the same PGP key that you used for signing the tarball.
361 (Use e.g. `M-x mml-secure-message-sign' in `message-mode' to sign
364 13. After a release, update the Emacs pages as described below.
366 14. After a release, bump the Emacs version on the release branch.
367 There is no need to bump the version after a pretest; the version
368 is bumped before the next pretest or release instead.
370 If the released version was XX.Y, use 'set-version' from
371 admin/admin.el to bump the version on the release branch to
372 XX.Y.50. Commit the changes.
374 UPDATING THE EMACS WEB PAGES AFTER A RELEASE
376 As soon as possible after a release, the Emacs web pages at
377 https://www.gnu.org/software/emacs/ should be updated.
378 (See admin/notes/www for general information.)
380 The pages to update are:
382 emacs.html (for a new major release, a more thorough update is needed)
384 add the new NEWS file as news/NEWS.xx.y
385 Copy new etc/MACHINES to MACHINES and CONTRIBUTE to CONTRIBUTE
387 For every new release, a banner is displayed on top of the emacs.html
388 page. Uncomment and the release banner in emacs.html. Keep it on the
389 page for about a month, then comment it again. The new release banner
392 <div class="release-banner">
393 <div class="container">
394 <h2><em>Emacs 28.1 is out</em>, download it <a href="download.html">here</a>!</h2>
398 Also, make sure the copyright years at the bottom of emacs.html are
401 The file download.html may need to be updated, for example if the
402 MS-Windows binaries will be signed by a different person/key than
403 those mentioned there.
405 Next, regenerate the various manuals in HTML, PDF, and PS formats:
407 Invoke ./admin/make-manuals from the top-level directory of the
408 Emacs source tree that contains the manuals for which you want to
409 produce HTML docs. This creates the 'manual' directory and
410 populates it with the necessary files.
412 If you have Texinfo installed locally, make-manuals might fail if it
413 cannot find epsf.tex. In that case define in the environment
415 TEXINPUTS=:/path/to/texinfo-tree/doc
417 where /path/to/texinfo-tree is the absolute file name of the
418 top-level directory where you have the Texinfo source tree. Then
421 make-manuals can also fail if the HTML manuals produced by Texinfo
422 violate some of the assumptions admin/admin.el makes about the
423 format of the produced HTML. Debug these problems and resolve them,
424 then re-run make-manuals. (Each time you run make-manuals, it
425 empties the manuals/ directory and regenerates the files there, but
426 if the files in manuals/ can be used without regeneration, i.e. if
427 the problem you solved doesn't affect the produced HTML, you can
428 invoke make-manuals with the -c switch, which will make the process
431 Now change to the 'manual' directory and invoke upload-manuals:
433 ../admin/upload-manuals /path/to/webpages/cvs/checkout
435 where /path/to/webpages/cvs/checkout is the place where you have the
436 CVS checkout of the Emacs Web pages, with subdirectories 'manual'
437 and 'refcards'. This moves the produced manuals to directories in
438 the Web pages CVS checkout tree, and also invokes CVS commands to
439 commit changed files, add new files, and remove stale files that are
440 no longer part of the manuals.
442 If upload-manuals fails, resolve the problems and re-invoke it.
443 This requires running make-manuals again, since upload-manuals
444 destructively modifies the 'manual' directory where you invoke it.
446 If new files fail to be "cvs add"ed, they need to be manually
447 removed from under /path/to/webpages/cvs/checkout before retrying
448 upload-manuals, because if they exist, they will not be handled as
449 "new" files, and will not be "cvs add"ed by the next run of the
452 Also, upload-manuals invokes "cvs commit -f", so if you run it
453 several times, some files will be committed more than once even
454 though they were not changed in-between. Suck it up.
456 All the added and removed files need to be committed, so next fire
457 up Emacs, type "C-x v d" to invoke vc-dir on the Web pages checkout,
458 and use "C-x v v" and other VC commands to commit all the files that
459 upload-manuals didn't automatically commit. (You can also do that
460 with manual CVS commands, of course, but this is not recommended.)
462 Next, make sure that manual/index.html file is consistent with the
463 info/dir file in the branch for which you are producing the manuals,
464 in that it mentions all the manuals. It could be outdated if
465 manuals were added or removed since the last release.
467 For each new manual, a file manual/MANUAL.html (where MANUAL is the
468 name of the manual) should be created from the template in
469 manual/eww.html, after editing the title and the Copyright years,
470 and the links in it changed to point to the appropriate files in the
471 manual/html_node/ and manual/html_mono/ subdirectories.
473 In addition, the file refcards/index.html should be audited to make
474 sure it includes the up-to-date list of refcards actually produced
475 and put under that subdirectory.
477 Browsing <https://web.cvs.savannah.gnu.org/viewvc/?root=emacs> is one
478 way to check for any files that still need updating.