admin/make-tarball.txt

   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
   4
   5
   6 Steps to take before starting on the first pretest in any release sequence:
   7
   8 0.  The release branch (e.g. emacs-26) 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.
  11
  12 1.  Decide on versions of m4 and autoconf, and ensure you will
  13     have them available for the duration of the release process.
  14
  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 probably needed only
  18     when preparing the first pretest for a major Emacs release.)
  19     Commit cus-edit.el if changed.
  20
  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
  24 General steps (for each step, check for possible errors):
  25
  26 1.   git pull     # fetch from the repository
  27      git status   # check for locally modified files
  28
  29     Ensure that you have a clean, unmodified state.
  30     If you switched in-place from another branch to the release branch,
  31     there could be inappropriate generated ignored files left over.
  32     You might want to use "git status --ignored" to check for such files,
  33     or some form of "git clean -x".  It's probably simpler and safer to
  34     make a new working directory exclusively for the release branch.
  35
  36 2.  Regenerate the etc/AUTHORS file:
  37       M-: (require 'authors) RET
  38       M-x authors RET
  39
  40     (This first updates the current versioned ChangeLog.N)
  41
  42     If there is an "*Authors Errors*" buffer, address the issues.
  43     If there was a ChangeLog typo, fix the relevant entry.
  44     If a file was deleted or renamed, consider adding an appropriate
  45     entry to authors-ignored-files, authors-valid-file-names, or
  46     authors-renamed-files-alist.
  47
  48     If necessary, repeat 'C-u M-x authors' after making those changes.
  49     Save the "*Authors*" buffer as etc/AUTHORS.
  50     Check the diff looks reasonable.  Maybe add entries to
  51     authors-ambiguous-files or authors-aliases, and repeat.
  52     Commit any fixes to authors.el.
  53
  54 3.  Set the version number (M-x load-file RET admin/admin.el RET, then
  55     M-x set-version RET).  For a pretest, start at version .90.  After
  56     .99, use .990 (so that it sorts).
  57
  58     The final pretest should be a release candidate.
  59     Before a release candidate is made, the tasks listed in
  60     admin/release-process must be completed.
  61
  62     Set the version number to that of the actual release.  Pick a date
  63     about a week from now when you intend to make the release.  Use M-x
  64     add-release-logs to add entries to etc/HISTORY and the ChangeLog
  65     file.  It's best not to commit these files until the release is
  66     actually made.  Merge the entries from (unversioned) ChangeLog
  67     into the top of the current versioned ChangeLog.N and commit that
  68     along with etc/HISTORY.  Then you can tag that commit as the
  69     release.
  70
  71     Name the tar file as emacs-XX.Y-rc1.tar.  If all goes well in the
  72     following week, you can simply rename the file and use it for the
  73     actual release.  If you need another release candidate, remember
  74     to adjust the ChangeLog and etc/HISTORY entries.
  75
  76     If you need to change only a file(s) that cannot possibly affect
  77     the build (README, ChangeLog, NEWS, etc.) then rather than doing
  78     an entirely new build, it is better to unpack the existing
  79     tarfile, modify the file(s), and tar it back up again.
  80
  81     Never replace an existing tarfile!  If you need to fix something,
  82     always upload it with a different name.
  83
  84 4.   autoreconf -i -I m4 --force
  85      make bootstrap
  86
  87      make -C etc/refcards
  88      make -C etc/refcards clean
  89
  90     If etc/refcards does not build you may need to downgrade or
  91     upgrade your TeX installation, or do that part of the build by
  92     hand.  For clues, search for the string "refcard" in the file
  93     admin/release-process.
  94
  95 5.  Copy lisp/loaddefs.el to lisp/ldefs-boot.el.
  96
  97     Commit ChangeLog.N, etc/AUTHORS, lisp/ldefs-boot.el, and the
  98     files changed by M-x set-version.
  99
 100     If someone else made a commit between step 1 and now,
 101     you need to repeat from step 4 onwards.  (You can commit the files
 102     from step 2 and 3 earlier to reduce the chance of this.)
 103
 104 6.  ./make-dist --snapshot --no-compress
 105
 106     Check the contents of the new tar with admin/diff-tar-files
 107     against the previous release (if this is the first pretest) or the
 108     previous pretest.  If you did not make the previous pretest
 109     yourself, find it at <https://alpha.gnu.org/gnu/emacs/pretest>.
 110     Releases are of course at <https://ftp.gnu.org/pub/gnu/emacs/>.
 111
 112     If this is the first pretest of a major release, just comparing
 113     with the previous release may overlook many new files.  You can try
 114     something like 'find . | sort' in a clean repository, and compare the
 115     results against the new tar contents.
 116
 117 7.   tar -xf emacs-NEW.tar; cd emacs-NEW
 118      ./configure --prefix=/tmp/emacs && make && make install
 119     Use 'script' or M-x compile to save the compilation log in
 120     compile-NEW.log and compare it against an old one.  The easiest way
 121     to do that is to visit the old log in Emacs, change the version
 122     number of the old Emacs to __, do the same with the new log and do
 123     M-x ediff.  Especially check that Info files aren't built, and that
 124     no autotools (autoconf etc) run.
 125
 126 8.  cd EMACS_ROOT_DIR && git tag -a TAG && git push origin tag TAG
 127     TAG is emacs-XX.Y.ZZ for a pretest, emacs-XX.Y for a release.
 128
 129 9. Decide what compression schemes to offer.
 130     For a release, at least gz and xz:
 131       gzip --best --no-name -c emacs-NEW.tar > emacs-NEW.tar.gz
 132       xz -c emacs-NEW.tar > emacs-NEW.tar.xz
 133     For pretests, just xz is probably fine (saves bandwidth).
 134
 135     Now you should upload the files to the GNU ftp server.  In order to
 136     do that, you must be registered as an Emacs maintainer and have your
 137     GPG key acknowledged by the ftp people.  For instructions, see
 138     https://www.gnu.org/prep/maintain/html_node/Automated-Upload-Registration.html
 139     The simplest method to upload is to use the gnulib
 140     <https://www.gnu.org/s/gnulib/> script "build-aux/gnupload":
 141
 142     For a pretest:
 143      gnupload [--user your@gpg.key.email] --to alpha.gnu.org:emacs/pretest \
 144        FILE.gz FILE.xz ...
 145
 146     For a release:
 147      gnupload [--user your@gpg.key.email] --to ftp.gnu.org:emacs \
 148        FILE.gz FILE.xz ...
 149
 150     You only need the --user part if you have multiple GPG keys and do
 151     not want to use the default.
 152     Obviously, if you do not have a fast uplink, be prepared for the
 153     upload to take a while.
 154
 155
 156     If you prefer to do it yourself rather than use gnupload:
 157
 158     For each FILE, create a detached GPG binary signature and a
 159     clearsigned directive file like this:
 160
 161      gpg -b FILE
 162      echo directory: emacs/pretest > FILE.directive      (for a pretest)
 163      echo directory: emacs > FILE.directive              (for a release)
 164      gpg --clearsign FILE.directive
 165     Upload by anonymous ftp to ftp://ftp-upload.gnu.org/ the files FILE,
 166     FILE.sig, FILE.directive.asc.
 167     For a release, place the files in the /incoming/ftp directory.
 168     For a pretest, place the files in /incoming/alpha instead, so that
 169     they appear on https://alpha.gnu.org/.
 170
 171 10. After five minutes, verify that the files are visible at
 172     https://alpha.gnu.org/gnu/emacs/pretest/ for a pretest, or
 173     https://ftp.gnu.org/gnu/emacs/ for a release.
 174
 175     Download them and check the signatures.  Check they build.
 176
 177 11. Send an announcement to: emacs-devel, and bcc: info-gnu-emacs@gnu.org.
 178     For a pretest, also bcc: platform-testers@gnu.org.
 179     For a release, also bcc: info-gnu@gnu.org.
 180     (The reason for using bcc: is to make it less likely that people
 181     will followup on the wrong list.)
 182     See the info-gnu-emacs mailing list archives for the form
 183     of past announcements.  The first pretest announcement, and the
 184     release announcement, should have more detail.
 185     Use the emacs-devel topic 'emacs-announce'.  The best way to do
 186     this is to add a header "Keywords: emacs-announce" to your mail.
 187     (You can also put it in the Subject, but this is not as good
 188     because replies that invariably are not announcements also get
 189     sent out as if they were.)
 190
 191 12. After a release, update the Emacs pages as below.
 192
 193
 194 UPDATING THE EMACS WEB PAGES AFTER A RELEASE
 195
 196 As soon as possible after a release, the Emacs web pages should be updated.
 197 Anyone with write access to the Emacs code repository can do this.
 198 For instructions, see <https://savannah.gnu.org/cvs/?group=emacs>.
 199 Changes go live more or less as soon as they are committed.
 200
 201 The pages to update are:
 202
 203 emacs.html (for a new major release, a more thorough update is needed)
 204 history.html
 205
 206 For every new release, a banner is displayed on top of the emacs.html
 207 page.  Uncomment and the release banner in emacs.html.  Keep it on the
 208 page for about a month, then comment it again.
 209
 210 Use M-x make-manuals from admin/admin.el to regenerate the html
 211 manuals in manual/.  If there are new manuals, add appropriate index
 212 pages in manual/ and add them to manual/index.html.  In the
 213 manual/html_node directory, delete any old manual pages that are no
 214 longer present.
 215
 216 Tar up the generated html_node/emacs/ and elisp/ directories and update
 217 the files manual/elisp.html_node.tar.gz and emacs.html_node.tar.gz.
 218 Use GNU Tar 1.28 or later so that the tarballs are more reproducible,
 219 as follows:
 220
 221   cd manual
 222   tar='tar --numeric-owner --owner=0 --group=0 --mode=go+u,go-w --sort=name'
 223   gzip='gzip --best --no-name'
 224   $tar -cf - html_node/emacs | $gzip >emacs.html_node.tar.gz
 225   $tar -cf - html_node/elisp | $gzip >elisp.html_node.tar.gz
 226
 227 Use M-x make-manuals-dist from admin/admin.el to update the
 228 manual/*.tar files.
 229
 230 Add compressed copies of the main info pages from the tarfile to manual/info/
 231 as follows:
 232
 233   cd manual
 234   mkdir info
 235   gzip --best --no-name <../info/eintr.info >info/eintr.info.gz
 236   gzip --best --no-name <../info/elisp.info >info/elisp.info.gz
 237   gzip --best --no-name <../info/emacs.info >info/emacs.info.gz
 238
 239 Update the refcards/pdf/ and ps/ directories, and also
 240 refcards/emacs-refcards.tar.gz (use make -C etc/refcards pdf ps dist).
 241
 242 FIXME: The above instructions are not quite complete, as they do not
 243 specify the manual procedure used to copy the generated files in the
 244 'manual' directory to the corresponding web files, and to cvs remove
 245 and add files as needed.  Also, they are missing some files, e.g.,
 246 they generate manual/html_mono/ada-mode.html but do not generate the
 247 top-level ada-mode.html file for the one-node-per-page version; this
 248 is currently done by hand.
 249
 250 Browsing <https://web.cvs.savannah.gnu.org/viewvc/?root=emacs> is one
 251 way to check for any files that still need updating.