1
0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2024-12-05 08:53:45 +00:00
emacs/admin/make-tarball.txt
2023-05-14 16:11:44 +03:00

456 lines
20 KiB
Plaintext

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.)
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. ./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 <https://alpha.gnu.org/gnu/emacs/pretest>.
Releases are of course at <https://ftp.gnu.org/pub/gnu/emacs/>.
./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.
7. 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.
8. 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"
9. 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
<https://www.gnu.org/s/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/.
10. 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).
11. 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.)
12. After a release, update the Emacs pages as described below.
13. 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:
<div class="release-banner">
<div class="container">
<h2><em>Emacs 28.1 is out</em>, download it <a href="download.html">here</a>!</h2>
</div>
</div>
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.
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 <https://web.cvs.savannah.gnu.org/viewvc/?root=emacs> is one
way to check for any files that still need updating.