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