emacs/admin/make-tarball.txt

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

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
    <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/.

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:

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

  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 <https://web.cvs.savannah.gnu.org/viewvc/?root=emacs> is one
way to check for any files that still need updating.