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