Instructions to create pretest or release tarballs. -*- coding: utf-8 -*- -- originally written by Gerd Moellmann, amended by Francesco Potortì with the initial help of Eli Zaretskii Steps to take before starting on the first pretest in any release sequence: 0. The release branch (e.g. emacs-28) should already have been made and you should use it for all that follows. Diffs from this branch should be going to the emacs-diffs mailing list. 1. Decide on versions of m4 and autoconf, and ensure you will have them available for the duration of the release process. 2. Consider increasing the value of the variable 'customize-changed-options-previous-release' in cus-edit.el to refer to a newer version of Emacs. (This is now done when cutting the release branch, see admin/release-branch.txt, but it can't hurt to double check its value.) Commit cus-edit.el if changed. 3. Remove any old pretests from https://alpha.gnu.org/gnu/emacs/pretest. You can use 'gnupload --delete' (see below for more gnupload details). (We currently don't bother with this.) 4. Check that all new Lisp libraries belong to sensible packages. Run "make -C lisp finder-data" and check the diff of the generated file against the previously released Emacs version to see what has changed. General steps (for each step, check for possible errors): 1. git pull # fetch from the repository git status # check for locally modified files Ensure that you have a clean, unmodified state. If you switched in-place from another branch to the release branch, there could be inappropriate generated ignored files left over. You might want to use "git status --ignored" to check for such files, or some form of "git clean -x". It's probably simpler and safer to make a new working directory exclusively for the release branch. If the working directory has subdirectories created when making previous releases or pretests, remove those subdirectories, as the command which updates the ChangeLog file might attempt to recurse there and scan any ChangeLog.* files there. Make sure the tree is built, or at least configured. That's because some of the commands below run Make, so they need Makefiles to be present. For Emacs 28 and later, as long as --with-native-compilation is not the default, the tree needs to be configured with native-compilation enabled, to ensure all the pertinent *.elc files will end up in the tarball. Otherwise, the *.eln files might not build correctly on the user's system. ./autogen.sh ./configure --with-native-compilation && make For a release (as opposed to pretest), visit etc/NEWS and use the "M-x emacs-news-delete-temporary-markers" command to delete any left-over "---" and "+++" markers from etc/NEWS, as well as the "Temporary note" section at the beginning of that file, and commit etc/NEWS if it was modified. For a bug fix release (e.g. 28.2), delete any empty headlines too. 2. Regenerate the versioned ChangeLog.N and etc/AUTHORS files. The "M-x authors" command below will first update the current versioned ChangeLog.N file. For this to work correctly, make sure the top-level Makefile says PREFERRED_BRANCH = emacs-NN where NN is the version on the release branch from which you are producing the tarball. If NN is incorrect (which it usually is when starting a pretest of a new major release), update Makefile.in and re-run 'configure' to update Makefile. For the first pretest of a new major release, consider starting a new top-level ChangeLog.N file if the last versioned ChangeLog.N file is too large. A good point to start a new ChangeLog.N file is when the last one gets larger than 5 MiB, or when you make the first pretest of a new major release, whichever happens later. If so, start a new ChangeLog.N file by bumping N, and also update the line in top-level Makefile.in which says CHANGELOG_HISTORY_INDEX_MAX = N by incrementing the value of N by 1; then regenerate Makefile. After bumping N, you need to actually create and commit ChangeLog.N with the updated N, otherwise "M-x authors" below will fail. The easiest way of creating the new ChangeLog.N is to rename the file ChangeLog (without the .N suffix) left over from the last major release (it is usually unversioned) and commit it. Now: M-: (require 'authors) RET M-x authors RET If this says "Problem updating ChangeLog", find the reason for the failure of the command it runs, viz.: make -C ROOT change-history-nocommit (where ROOT is the top-level directory where you run this). It could be because there are uncommitted changes in ChangeLog.N, for example. One possible way forward is to invoke "C-u M-x authors", which will skip updating the versioned ChangeLog.N file. After "M-x authors" finishes, if there is an "*Authors Errors*" buffer, address the issues. If there was a ChangeLog typo, fix the relevant entry. If a file was deleted or renamed, consider adding an appropriate entry to variables authors-ignored-files, authors-valid-file-names, or authors-renamed-files-alist in authors.el. If some authors are "ignored", consider adding entries to the author-aliases variable. If necessary, repeat 'C-u M-x authors' after making those changes. Save the "*Authors*" buffer as etc/AUTHORS. Check the diff looks reasonable. Maybe add more entries to authors-ambiguous-files or authors-aliases, and repeat. Commit any fixes to authors.el. 3. Set the version number (M-x load-file RET admin/admin.el RET, then M-x set-version RET). For a pretest, start at version .90. After .99, use .990 (so that it sorts). Commit the resulting changes as one, with nothing else included, and using a log message of the format "Bump Emacs version to ...", so that the commit can be skipped when merging branches (see admin/gitmerge.el). The final pretest should be a release candidate. Before a release candidate is made, the tasks listed in admin/release-process must be completed. Set the version number to that of the actual release (commit in one, as described above). Pick a date about a week from now when you intend to make the release. Use M-x add-release-logs from admin/admin.el to add entries to etc/HISTORY and the ChangeLog file. It's best not to commit these files until the release is actually made. Merge the entries from (unversioned) ChangeLog into the top of the current versioned ChangeLog.N and commit that along with etc/HISTORY. Then you can tag that commit as the release. Alternatively, you can commit and tag with the RC tag right away, and delay the final tagging until you actually decide to make a release and announce it. The "git tag" command can tag a specific commit if you give it the SHA1 of that commit, even if additional commits have been pushed in the meantime. Name the tar file as emacs-XX.Y-rc1.tar. If all goes well in the following week, you can simply rename the file and use it for the actual release. If you need another release candidate, remember to adjust the ChangeLog and etc/HISTORY entries. If you need to change only a file(s) that cannot possibly affect the build (README, ChangeLog, NEWS, etc.) then rather than doing an entirely new build, it is better to unpack the existing tarfile, modify the file(s), and tar it back up again. Never replace an existing tarfile! If you need to fix something, always upload it with a different name. 4. autoreconf -i -I m4 --force make bootstrap The below script checks for any mistakes in the source text of manual pages. Fix any errors and re-run the script to verify. ./admin/check-man-pages Then do this: make -C etc/refcards make -C etc/refcards clean If some of the etc/refcards, especially the non-English ones, fail to build, you probably need to install some TeX/LaTeX packages, in particular for foreign language support. For more information, search for the string "refcard" in the file admin/release-process. (ru-refcard causes numerous "Underfull hbox" and "Overfull hbox" messages from TeX, but those seem to be harmless, as the result looks just fine.) 5. Copy lisp/loaddefs.el to lisp/ldefs-boot.el. After copying, edit ldefs-boot.el to add ;; no-byte-compile: t to its file-local variables section, otherwise make-dist will complain. Commit ChangeLog.N, etc/AUTHORS, lisp/ldefs-boot.el, and the files changed by M-x set-version. Note that the set-version changes should be committed separately, as described in step 3 above, to avoid them being merged to master. The lisp/ldefs-boot.el file should not be merged to master either, so it could be added to the same commit or committed separately. The easiest way of doing that is "C-x v d ROOT-DIR RET", then go to the first modified file, press 'M' to mark all modified files, and finally 'v' to commit them. Make sure the commit log message mentions all the changes in all modified files, as by default 'v' doesn't necessarily do so. If someone else made a commit between step 1 and now, you need to repeat from step 4 onwards. (You can commit the files from step 2 and 3 earlier to reduce the chance of this.) 6. If there has been a change in who is the Emacs maintainer since the last release, update doc/misc/ack.texi and admin/MAINTAINERS to reflect this. You can commit this separately. 7. ./make-dist --snapshot --no-compress Check the contents of the new tar with admin/diff-tar-files against the previous release (if this is the first pretest) or the previous pretest. If you did not make the previous pretest yourself, find it at . Releases are of course at . ./admin/diff-tar-files emacs-OLD.tar emacs-NEW.tar Alternatively, if you want to use the compressed tarballs (which diff-tar-files doesn't understand): tar tJf emacs-OLD.tar.xz | sed -e 's,^[^/]*,,' | sort > old_tmp tar tJf emacs-NEW.tar.xz | sed -e 's,^[^/]*,,' | sort > new_tmp diff -u old_tmp new_tmp If this is the first pretest of a major release, just comparing with the previous release may overlook many new files. You can try something like 'find . | sort' in a clean repository, and compare the results against the new tar contents. Another alternative is using something like: tar cf - emacs-NEW | tar t -C /tmp | grep -Ev "\.(o|d)$" | sort Where emacs-NEW is the directory containing your clean repository. The output of this command might be easier to compare to the tarball than the one you get from find. 8. tar xf emacs-NEW.tar; cd emacs-NEW ./configure --prefix=/tmp/emacs && make check && make install Use 'script' or M-x compile to save the compilation log in compile-NEW.log and compare it against an old one. The easiest way to do that is to visit the old log in Emacs, change the version number of the old Emacs to __, do the same with the new log and do M-x ediff. Especially check that Info files aren't built, and that no autotools (autoconf etc) run. 9. You can now tag the release/pretest and push it together with the last commit: cd EMACS_ROOT_DIR && git tag -a TAG -m "Emacs TAG" git push git push --tags Here TAG is emacs-XX.Y.ZZ for a pretest, emacs-XX.Y for a release. For a release, if you are producing a release candidate first, use emacs-XX.Y-rcN (N = 1, 2, ...) when you tar the RC, and add the actual release tag later, when the official release tarball is uploaded to ftp.gnu.org. When adding a tag later, it is safer to use the SHA1 of the last commit which went into the release tarball, in case there were some intervening commits since then: git tag -a TAG -m "Emacs TAG" SHA1 git push --tags In the past, we were not always consistent with the annotation (i.e. -m "Emacs TAG"). The preferred format is like this for a pretest, release candidate and final release: git tag -a emacs-28.0.90 -m "Emacs 28.0.90 pretest" git tag -a emacs-28.1-rc1 -m "Emacs 28.1 RC1" git tag -a emacs-28.1 -m "Emacs 28.1 release" 10. Decide what compression schemes to offer. For a release, at least gz and xz: gzip --best --no-name -c emacs-NEW.tar > emacs-NEW.tar.gz xz -c emacs-NEW.tar > emacs-NEW.tar.xz For pretests, just xz is probably fine (saves bandwidth). Now you should upload the files to the GNU ftp server. In order to do that, you must be registered as an Emacs maintainer and have your GPG key acknowledged by the ftp people. For instructions, see https://www.gnu.org/prep/maintain/html_node/Automated-Upload-Registration.html The simplest method to upload is to use the gnulib script "build-aux/gnupload": For a pretest: gnupload [--user your@gpg.key.email] --to alpha.gnu.org:emacs/pretest \ FILE.gz FILE.xz ... For a release: gnupload [--user your@gpg.key.email] --to ftp.gnu.org:emacs \ FILE.gz FILE.xz ... You only need the --user part if you have multiple GPG keys and do not want to use the default. Instead of "your@gpg.key.email" you could also use the fingerprint of the key, a 40-digit hex number. (Alternatively, define default-key in your ~/.gnupg/gpg.conf file.) Obviously, if you do not have a fast uplink, be prepared for the upload to take a while. If you prefer to do it yourself rather than use gnupload: For each FILE, create a detached GPG binary signature and a clearsigned directive file like this: gpg -b FILE echo directory: emacs/pretest > FILE.directive (for a pretest) echo directory: emacs > FILE.directive (for a release) gpg --clearsign FILE.directive Upload by anonymous ftp to ftp://ftp-upload.gnu.org/ the files FILE, FILE.sig, FILE.directive.asc. For a release, place the files in the /incoming/ftp directory. For a pretest, place the files in /incoming/alpha instead, so that they appear on https://alpha.gnu.org/. 11. After five minutes, verify that the files are visible at https://alpha.gnu.org/gnu/emacs/pretest/ for a pretest, or https://ftp.gnu.org/gnu/emacs/ for a release. Download them and check the signatures and SHA1/SHA256 checksums. Check they build (./configure --with-native-compilation). 12. Send an announcement to: emacs-devel, and bcc: info-gnu-emacs@gnu.org. For a pretest, also bcc: platform-testers@gnu.org. For a release, also bcc: info-gnu@gnu.org. (The reason for using bcc: is to make it less likely that people will followup on the wrong list.) See the info-gnu-emacs mailing list archives for the form of past announcements. The first pretest announcement, and the release announcement, should have more detail. Use the emacs-devel topic 'emacs-announce'. The best way to do this is to add a header "Keywords: emacs-announce" to your mail. (You can also put it in the Subject, but this is not as good because replies that invariably are not announcements also get sent out as if they were.) To create the included SHA1 and SHA256 checksums, run: sha1sum emacs-NEW.tar.xz sha256sum emacs-NEW.tar.xz You can optionally sign the announcement email, preferably using the same PGP key that you used for signing the tarball. (Use e.g. `M-x mml-secure-message-sign' in `message-mode' to sign an email.) 13. After a release, update the Emacs pages as described below. 14. After a release, bump the Emacs version on the release branch. There is no need to bump the version after a pretest; the version is bumped before the next pretest or release instead. If the released version was XX.Y, use 'set-version' from admin/admin.el to bump the version on the release branch to XX.Y.50. Commit the changes. UPDATING THE EMACS WEB PAGES AFTER A RELEASE As soon as possible after a release, the Emacs web pages at https://www.gnu.org/software/emacs/ should be updated. (See admin/notes/www for general information.) The pages to update are: emacs.html (for a new major release, a more thorough update is needed) history.html add the new NEWS file as news/NEWS.xx.y Copy new etc/MACHINES to MACHINES and CONTRIBUTE to CONTRIBUTE For every new release, a banner is displayed on top of the emacs.html page. Uncomment and the release banner in emacs.html. Keep it on the page for about a month, then comment it again. The new release banner looks like this:

Emacs 28.1 is out, download it here!

Also, make sure the copyright years at the bottom of emacs.html are up-to-date. The file download.html may need to be updated, for example if the MS-Windows binaries will be signed by a different person/key than those mentioned there. Next, regenerate the various manuals in HTML, PDF, and PS formats: Invoke ./admin/make-manuals from the top-level directory of the Emacs source tree that contains the manuals for which you want to produce HTML docs. This creates the 'manual' directory and populates it with the necessary files. If you have Texinfo installed locally, make-manuals might fail if it cannot find epsf.tex. In that case define in the environment TEXINPUTS=:/path/to/texinfo-tree/doc where /path/to/texinfo-tree is the absolute file name of the top-level directory where you have the Texinfo source tree. Then re-run make-manuals. make-manuals can also fail if the HTML manuals produced by Texinfo violate some of the assumptions admin/admin.el makes about the format of the produced HTML. Debug these problems and resolve them, then re-run make-manuals. (Each time you run make-manuals, it empties the manuals/ directory and regenerates the files there, but if the files in manuals/ can be used without regeneration, i.e. if the problem you solved doesn't affect the produced HTML, you can invoke make-manuals with the -c switch, which will make the process much faster.) Now change to the 'manual' directory and invoke upload-manuals: ../admin/upload-manuals /path/to/webpages/cvs/checkout where /path/to/webpages/cvs/checkout is the place where you have the CVS checkout of the Emacs Web pages, with subdirectories 'manual' and 'refcards'. This moves the produced manuals to directories in the Web pages CVS checkout tree, and also invokes CVS commands to commit changed files, add new files, and remove stale files that are no longer part of the manuals. If upload-manuals fails, resolve the problems and re-invoke it. This requires running make-manuals again, since upload-manuals destructively modifies the 'manual' directory where you invoke it. If new files fail to be "cvs add"ed, they need to be manually removed from under /path/to/webpages/cvs/checkout before retrying upload-manuals, because if they exist, they will not be handled as "new" files, and will not be "cvs add"ed by the next run of the script. Also, upload-manuals invokes "cvs commit -f", so if you run it several times, some files will be committed more than once even though they were not changed in-between. Suck it up. All the added and removed files need to be committed, so next fire up Emacs, type "C-x v d" to invoke vc-dir on the Web pages checkout, and use "C-x v v" and other VC commands to commit all the files that upload-manuals didn't automatically commit. (You can also do that with manual CVS commands, of course, but this is not recommended.) Next, make sure that manual/index.html file is consistent with the info/dir file in the branch for which you are producing the manuals, in that it mentions all the manuals. It could be outdated if manuals were added or removed since the last release. For each new manual, a file manual/MANUAL.html (where MANUAL is the name of the manual) should be created from the template in manual/eww.html, after editing the title and the Copyright years, and the links in it changed to point to the appropriate files in the manual/html_node/ and manual/html_mono/ subdirectories. In addition, the file refcards/index.html should be audited to make sure it includes the up-to-date list of refcards actually produced and put under that subdirectory. Browsing is one way to check for any files that still need updating.