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     If you need to change only a file(s) that cannot possibly affect
  67     the build (README, ChangeLog, NEWS, etc.) then rather than doing
  68     an entirely new build, it is better to unpack the existing
  69     tarfile, modify the file(s), and tar it back up again.
  70
  71     Never replace an existing tarfile!  If you need to fix something,
  72     always upload it with a different name.
  73
  74 4.   autoreconf -i -I m4 --force
  75      make bootstrap
  76
  77      make -C etc/refcards
  78      make -C etc/refcards clean
  79
  80 5.  Copy lisp/loaddefs.el to lisp/ldefs-boot.el.
  81
  82     Commit etc/AUTHORS, lisp/ldefs-boot.el, and the files changed
  83     by M-x set-version.
  84
  85     If someone else made a commit between step 1 and now,
  86     you need to repeat from step 4 onwards.  (You can commit the files
  87     from step 2 and 3 earlier to reduce the chance of this.)
  88
  89 6.  ./make-dist --snapshot --no-compress
  90
  91     Check the contents of the new tar with admin/diff-tar-files
  92     against the previous release (if this is the first pretest) or the
  93     previous pretest.  If you did not make the previous pretest
  94     yourself, find it at <ftp://alpha.gnu.org/gnu/emacs/pretest>.
  95     Releases are of course at <ftp://ftp.gnu.org/pub/gnu/emacs/>.
  96
  97     If this is the first pretest of a major release, just comparing
  98     with the previous release may overlook many new files.  You can try
  99     something like 'find . | sort' in a clean repository, and compare the
 100     results against the new tar contents.
 101
 102 7.   tar -xf emacs-NEW.tar; cd emacs-NEW
 103      ./configure --prefix=/tmp/emacs && make && make install
 104     Use 'script' or M-x compile to save the compilation log in
 105     compile-NEW.log and compare it against an old one.  The easiest way
 106     to do that is to visit the old log in Emacs, change the version
 107     number of the old Emacs to __, do the same with the new log and do
 108     M-x ediff.  Especially check that Info files aren't built, and that
 109     no autotools (autoconf etc) run.
 110
 111 8.  cd EMACS_ROOT_DIR && git tag -a TAG && git push origin tag TAG
 112     TAG is emacs-XX.Y.ZZ for a pretest, emacs-XX.Y for a release.
 113
 114 9. Decide what compression schemes to offer.
 115     For a release, at least gz and xz:
 116       gzip --best -c emacs-NEW.tar > emacs-NEW.tar.gz
 117       xz -c emacs-NEW.tar > emacs-NEW.tar.xz
 118     For pretests, just xz is probably fine (saves bandwidth).
 119
 120     Now you should upload the files to the GNU ftp server.  In order to
 121     do that, you must be registered as an Emacs maintainer and have your
 122     GPG key acknowledged by the ftp people.  For instructions, see
 123     http://www.gnu.org/prep/maintain/html_node/Automated-Upload-Registration.html
 124     The simplest method to upload is to use the gnulib
 125     <http://www.gnu.org/s/gnulib/> script "build-aux/gnupload":
 126
 127     For a pretest:
 128      gnupload [--user your@gpg.key.email] --to alpha.gnu.org:emacs/pretest \
 129        FILE.gz FILE.xz ...
 130
 131     For a release:
 132      gnupload [--user your@gpg.key.email] --to ftp.gnu.org:emacs \
 133        FILE.gz FILE.xz ...
 134
 135     You only need the --user part if you have multiple GPG keys and do
 136     not want to use the default.
 137     Obviously, if you do not have a fast uplink, be prepared for the
 138     upload to take a while.
 139
 140
 141     If you prefer to do it yourself rather than use gnupload:
 142
 143     For each FILE, create a detached GPG binary signature and a
 144     clearsigned directive file like this:
 145
 146      gpg -b FILE
 147      echo directory: emacs/pretest > FILE.directive      (for a pretest)
 148      echo directory: emacs > FILE.directive              (for a release)
 149      gpg --clearsign FILE.directive
 150     Upload by anonymous ftp to ftp://ftp-upload.gnu.org/ the files FILE,
 151     FILE.sig, FILE.directive.asc.
 152     For a release, place the files in the /incoming/ftp directory.
 153     For a pretest, place the files in /incoming/alpha instead, so that
 154     they appear on ftp://alpha.gnu.org/.
 155
 156 10. After five minutes, verify that the files are visible at
 157     ftp://alpha.gnu.org/gnu/emacs/pretest/ for a pretest, or
 158     ftp://ftp.gnu.org/gnu/emacs/ for a release.
 159
 160     Download them and check the signatures.  Check they build.
 161
 162 11. Send an announcement to: emacs-devel, and bcc: info-gnu-emacs@gnu.org.
 163     For a pretest, also bcc: platform-testers@gnu.org.
 164     For a release, also bcc: info-gnu@gnu.org.
 165     (The reason for using bcc: is to make it less likely that people
 166     will followup on the wrong list.)
 167     See the info-gnu-emacs mailing list archives for the form
 168     of past announcements.  The first pretest announcement, and the
 169     release announcement, should have more detail.
 170
 171 12. After a release, update the Emacs pages as below.
 172
 173
 174 UPDATING THE EMACS WEB PAGES AFTER A RELEASE
 175
 176 As soon as possible after a release, the Emacs web pages should be updated.
 177 Anyone with write access to the Emacs code repository can do this.
 178 For instructions, see <http://savannah.gnu.org/cvs/?group=emacs>.
 179 Changes go live more or less as soon as they are committed.
 180
 181 The pages to update are:
 182
 183 emacs.html (for a new major release, a more thorough update is needed)
 184 history.html
 185 add the new NEWS file as news/NEWS.xx.y
 186
 187 Use M-x make-manuals from admin/admin.el to regenerate the html
 188 manuals in manual/.  If there are new manuals, add appropriate index
 189 pages in manual/ and add them to manual/index.html.  In the
 190 manual/html_node directory, delete any old manual pages that are no
 191 longer present.
 192
 193 Tar up the generated html_node/emacs/ and elisp/ directories and update
 194 the files manual/elisp.html_node.tar.gz and emacs.html_node.tar.gz.
 195
 196 Use M-x make-manuals-dist from from admin/admin.el to update the
 197 manual/texi/ tarfiles.
 198
 199 Add compressed copies of the main info pages from the tarfile to manual/info/.
 200
 201 Update the refcards/pdf/ and ps/ directories, and also
 202 refcards/emacs-refcards.tar.gz (use make -C etc/refcards pdf ps dist).
 203
 204 Browsing <http://web.cvs.savannah.gnu.org/viewvc/?root=emacs> is one
 205 way to check for any files that still need updating.