emacs-27 291a421: * admin/make-tarball.txt: Improve and expand the instructions.

[Eli Zaretskii]

branch: emacs-27
commit 291a421c2e7420c36a0767f2c1e1d7317022f719
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    * admin/make-tarball.txt: Improve and expand the instructions.
---
 admin/make-tarball.txt | 51 ++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 43 insertions(+), 8 deletions(-)

diff --git a/admin/make-tarball.txt b/admin/make-tarball.txt
index bf682ec..65c6e86 100644
--- a/admin/make-tarball.txt
+++ b/admin/make-tarball.txt
@@ -88,6 +88,12 @@ General steps (for each step, check for possible errors):
     along with etc/HISTORY.  Then you can tag that commit as the
     release.
 
+    Alternatively, you can commit and tag with the RC tag right away,
+    and delay the final tagging until you actually decide to make a
+    release and announce it.  The "git tag" command can tag a specific
+    commit if you give it the SHA1 of that commit, even if additional
+    commits have been pushed in the meantime.
+
     Name the tar file as emacs-XX.Y-rc1.tar.  If all goes well in the
     following week, you can simply rename the file and use it for the
     actual release.  If you need another release candidate, remember
@@ -101,11 +107,11 @@ General steps (for each step, check for possible errors):
     Never replace an existing tarfile!  If you need to fix something,
     always upload it with a different name.
 
-4.   autoreconf -i -I m4 --force
-     make bootstrap
+4.    autoreconf -i -I m4 --force
+      make bootstrap
 
-     make -C etc/refcards
-     make -C etc/refcards clean
+      make -C etc/refcards
+      make -C etc/refcards clean
 
     If some of the etc/refcards, especially the non-English ones, fail
     to build, you probably need to install some TeX/LaTeX packages, in
@@ -119,13 +125,18 @@ General steps (for each step, check for possible errors):
 5.  Copy lisp/loaddefs.el to lisp/ldefs-boot.el.
 
     Commit ChangeLog.N, etc/AUTHORS, lisp/ldefs-boot.el, and the
-    files changed by M-x set-version.
+    files changed by M-x set-version.  The easiest way of doing that
+    is "C-x v d ROOT-DIR RET", then go to the first modified file,
+    press 'M' to mark all modified files, and finally 'v' to commit
+    them.  Make sure the commit log message mentions all the changes
+    in all modified files, as by default 'v' doesn't necessarily do
+    so.
 
     If someone else made a commit between step 1 and now,
     you need to repeat from step 4 onwards.  (You can commit the files
     from step 2 and 3 earlier to reduce the chance of this.)
 
-6.  ./make-dist --snapshot --no-compress
+6.   ./make-dist --snapshot --no-compress
 
     Check the contents of the new tar with admin/diff-tar-files
     against the previous release (if this is the first pretest) or the
@@ -133,6 +144,14 @@ General steps (for each step, check for possible errors):
     yourself, find it at <https://alpha.gnu.org/gnu/emacs/pretest>.
     Releases are of course at <https://ftp.gnu.org/pub/gnu/emacs/>.
 
+     ./admin/diff-tar-files emacs-OLD.tar.gz emacs-NEW.tar.gz
+
+    Alternatively:
+
+     tar tJf emacs-OLD.tar.xz | sed -e 's,^[^/]*,,' | sort > old_tmp
+     tar tJf emacs-NEW.tar.xz | sed -e 's,^[^/]*,,' | sort > new_tmp
+     diff -u old_tmp new_tmp
+
     If this is the first pretest of a major release, just comparing
     with the previous release may overlook many new files.  You can try
     something like 'find . | sort' in a clean repository, and compare the
@@ -140,6 +159,7 @@ General steps (for each step, check for possible errors):
 
 7.   tar -xf emacs-NEW.tar; cd emacs-NEW
      ./configure --prefix=/tmp/emacs && make check && make install
+
     Use 'script' or M-x compile to save the compilation log in
     compile-NEW.log and compare it against an old one.  The easiest way
     to do that is to visit the old log in Emacs, change the version
@@ -147,8 +167,23 @@ General steps (for each step, check for possible errors):
     M-x ediff.  Especially check that Info files aren't built, and that
     no autotools (autoconf etc) run.
 
-8.  cd EMACS_ROOT_DIR && git tag -a TAG && git push origin tag TAG
-    TAG is emacs-XX.Y.ZZ for a pretest, emacs-XX.Y for a release.
+8.  You can now tag the release/pretest and push it together with the
+    last commit:
+
+     cd EMACS_ROOT_DIR && git tag -a TAG -m "Emacs TAG"
+     git push
+     git push --tags
+
+    Here TAG is emacs-XX.Y.ZZ for a pretest, emacs-XX.Y for a release.
+    For a release, if you are producing a release candidate first, use
+    emacs-XX.Y-rcN (N = 1, 2, ...) when you tar the RC, and add the
+    actual release tag later, when the official release tarball is
+    uploaded to ftp.gnu.org.  When adding a tag later, it is safer to
+    use the SHA1 of the last commit which went into the release
+    tarball, in case there were some intervening commits since then:
+
+     git tag -a TAG -m "Emacs TAG" SHA1
+     git push --tags
 
 9. Decide what compression schemes to offer.
     For a release, at least gz and xz: