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-24) 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 automake 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 ftp://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 2.  Regenerate the etc/AUTHORS file:
  30       M-: (require 'authors) RET
  31       M-x authors RET
  32
  33     If there is an "*Authors Errors*" buffer, address the issues.
  34     If there was a ChangeLog typo, run "make change-history" and then
  35     fix the newest ChangeLog history file.  If a file was deleted or
  36     renamed, consider adding an appropriate entry to
  37     authors-ignored-files, authors-valid-file-names, or
  38     authors-renamed-files-alist.
  39
  40     If necessary, repeat M-x authors after making those changes.
  41     Save the "*Authors*" buffer as etc/AUTHORS.
  42     Check the diff looks reasonable.  Maybe add entries to
  43     authors-ambiguous-files or authors-aliases, and repeat.
  44     Commit any fixes to authors.el.
  45
  46 3.  Set the version number (M-x load-file RET admin/admin.el RET, then
  47     M-x set-version RET).  For a release, add released ChangeLog
  48     entries (create a ChangeLog symlink a la vc-dwim, then run M-x
  49     add-release-logs RET, then run the shell command 'vc-dwim --commit').
  50
  51     For a pretest, start at version .90.  After .99, use .990 (so that
  52     it sorts).
  53
  54     The final pretest should be a release candidate.  Set the version
  55     number to that of the actual release.  Pick a date about a week
  56     from now when you intend to make the release.  Use vc-dwim and
  57     M-x add-release-logs as described above to add commit messages
  58     that will appear in the tarball's automatically-generated ChangeLog
  59     file as entries for that date.
  60
  61     Name the tar file as emacs-XX.Y-rc1.tar.  If all goes well in the
  62     following week, you can simply rename the file and use it for the
  63     actual release.  If you need another release candidate, remember
  64     to adjust the ChangeLog entries.
  65
  66 4.   autoreconf -i -I m4 --force
  67      make bootstrap
  68
  69      make -C etc/refcards
  70      make -C etc/refcards clean
  71
  72 5.  Copy lisp/loaddefs.el to lisp/ldefs-boot.el.
  73
  74     Commit etc/AUTHORS, lisp/ldefs-boot.el, and the files changed
  75     by M-x set-version.
  76
  77     If someone else made a commit between step 1 and now,
  78     you need to repeat from step 4 onwards.  (You can commit the files
  79     from step 2 and 3 earlier to reduce the chance of this.)
  80
  81 6.  ./make-dist --snapshot --no-compress
  82
  83     Check the contents of the new tar with admin/diff-tar-files
  84     against the previous release (if this is the first pretest) or the
  85     previous pretest.  If you did not make the previous pretest
  86     yourself, find it at <ftp://alpha.gnu.org/gnu/emacs/pretest>.
  87     Releases are of course at <ftp://ftp.gnu.org/pub/gnu/emacs/>.
  88
  89     If this is the first pretest of a major release, just comparing
  90     with the previous release may overlook many new files.  You can try
  91     something like `find . | sort' in a clean repository, and compare the
  92     results against the new tar contents.
  93
  94 7.   tar -xf emacs-NEW.tar; cd emacs-NEW
  95      ./configure --prefix=/tmp/emacs && make && make install
  96     Use `script' or M-x compile to save the compilation log in
  97     compile-NEW.log and compare it against an old one.  The easiest way
  98     to do that is to visit the old log in Emacs, change the version
  99     number of the old Emacs to __, do the same with the new log and do
 100     M-x ediff.  Especially check that Info files aren't built, and that
 101     no autotools (autoconf etc) run.
 102
 103 8.  cd EMACS_ROOT_DIR && git tag -a TAG && git push origin tag TAG
 104     TAG is emacs-XX.Y.ZZ for a pretest, emacs-XX.Y for a release.
 105
 106 9. Decide what compression schemes to offer.
 107     For a release, at least gz and xz:
 108       gzip --best -c emacs-NEW.tar > emacs-NEW.tar.gz
 109       xz -c emacs-NEW.tar > emacs-NEW.tar.xz
 110     For pretests, just xz is probably fine (saves bandwidth).
 111
 112     Now you should upload the files to the GNU ftp server.  In order to
 113     do that, you must be registered as an Emacs maintainer and have your
 114     GPG key acknowledged by the ftp people.  For instructions, see
 115     http://www.gnu.org/prep/maintain/html_node/Automated-Upload-Registration.html
 116     The simplest method to upload is to use the gnulib
 117     <http://www.gnu.org/s/gnulib/> script "build-aux/gnupload":
 118
 119     For a pretest:
 120      gnupload [--user your@gpg.key.email] --to alpha.gnu.org:emacs/pretest \
 121        FILE.gz FILE.xz ...
 122
 123     For a release:
 124      gnupload [--user your@gpg.key.email] --to ftp.gnu.org:emacs \
 125        FILE.gz FILE.xz ...
 126
 127     You only need the --user part if you have multiple GPG keys and do
 128     not want to use the default.
 129     Obviously, if you do not have a fast uplink, be prepared for the
 130     upload to take a while.
 131
 132
 133     If you prefer to do it yourself rather than use gnupload:
 134
 135     For each FILE, create a detached GPG binary signature and a
 136     clearsigned directive file like this:
 137
 138      gpg -b FILE
 139      echo directory: emacs/pretest > FILE.directive      (for a pretest)
 140      echo directory: emacs > FILE.directive              (for a release)
 141      gpg --clearsign FILE.directive
 142     Upload by anonymous ftp to ftp://ftp-upload.gnu.org/ the files FILE,
 143     FILE.sig, FILE.directive.asc.
 144     For a release, place the files in the /incoming/ftp directory.
 145     For a pretest, place the files in /incoming/alpha instead, so that
 146     they appear on ftp://alpha.gnu.org/.
 147
 148 10. After five minutes, verify that the files are visible at
 149     ftp://alpha.gnu.org/gnu/emacs/pretest/ for a pretest, or
 150     ftp://ftp.gnu.org/gnu/emacs/ for a release.
 151
 152     Download them and check the signatures.  Check they build.
 153
 154 11. Send an announcement to: emacs-devel, and bcc: info-gnu-emacs@gnu.org.
 155     For a pretest, also bcc: platform-testers@gnu.org.
 156     For a release, also bcc: info-gnu@gnu.org.
 157     (The reason for using bcc: is to make it less likely that people
 158     will followup on the wrong list.)
 159     See the info-gnu-emacs mailing list archives for the form
 160     of past announcements.  The first pretest announcement, and the
 161     release announcement, should have more detail.
 162
 163 12. For a release, update the Emacs homepage emacs.html in the web repository.
 164     Also update history.html, and add the new NEWS file as news/NEWS.xx.y.
 165     Regenerate the html manuals (use make-manuals from admin.el).
 166     If there are new manuals, add appropriate index pages.
 167     Delete any old manual pages that are no longer present.