This document describes the release process used by GNU Emacs.

* RELEASE CYCLE

Our release cycles have three periods.

master is always open for new features.
In phases two and three, a single emacs-NN branch is open for bug fixes.
I.e., there is never more than one active emacs-NN branch.

We expect to make two non-emergency releases from each emacs-NN branch,
NN.1 and NN.2.

** Phase one: development on master only

New feature development, and bug fixes, on master.  No emacs-NN branches
are active: **no changes should be installed on any emacs-NN branches.**

The exception is emergency bug fix releases.  If the Emacs maintainers
think that your change justifies an emergency release from the most
recent emacs-NN branch, they'll co-ordinate installing your change on
that branch with you.

At the end of this phase, Emacs developers will be devoted to figuring
out what features to include in the next release and what features to
defer to a later release.

** Phase two: NN+1 on master, NN.1 on emacs-NN

At the beginning of this phase, a release branch called "emacs-NN"
("NN" represents the major version number of the new Emacs release)
will be cut from master.  See admin/release-branch.txt.

Thereafter, **all bug fixes** are installed on emacs-NN
(assuming the feature being fixed exists on that branch).
New features aren't allowed; these must continue to go to master.
From time to time, the emacs-NN branch is merged into master
so that master receives the bug fixes too.

Eventually we release Emacs NN.1 from the emacs-NN branch.
See admin/make-tarball.txt.

** Phase three: NN+1 on master, NN.2 on emacs-NN

We continue to install all bug fixes for features present in the NN.1
release **to the emacs-NN branch.**  In particular, avoid installing
bug fixes only to the master branch, or they will take unnecessarily
long to reach users.

Eventually we decide that there probably aren't important problems
remaining on the emacs-NN branch.  Then we release Emacs NN.2 and the
emacs-NN branch becomes inactive, except for emergency releases.
It's back to phase 1.

** Skipping phase one

Phase one is conceptually the first phase of every release cycle, but
often we skip directly from step 3 of one release cycle to step 2 of the
next.  I.e., we decide that there aren't important problems remaining on
the emacs-NN branch at the same time as we decide what features to
include in the next release.  Then we make the NN.2 release at around
the same time as we cut the emacs-NN+1 branch.

The important point is that it is a precondition on cutting the
emacs-NN+1 branch that we have decided there won't be another
non-emergency release from the emacs-NN branch, because we think it no
longer has any major problems.

** Discussion

The most recent of discussion of our practices in this area:
https://lists.gnu.org/archive/html/emacs-devel/2026-06/msg00524.html

* RELEASE-BLOCKING BUGS

We sometimes use the "blocking" feature of Debbugs for bugs that need to
be addressed in the next release.

At one point, bug#43018 was the tracking bug for release of 27.2 and
bug#39202 was the tracking bug for release 28.1.
Say bug#123 needed to be fixed for Emacs 27.2.
You'd send a message to control@debbugs.gnu.org saying

  block 43018 by 123

Change "block" to "unblock" to remove a bug from the list.  Closed
bugs are not listed as blockers, so you do not need to explicitly
unblock one that has been closed.  You may need to force an update of
the tracking bug with ctrl-f5/shift-reload to see the latest version.

If you use the debbugs package from GNU ELPA, you can apply the
following command to see all bugs which block a given release:

  (debbugs-gnu-emacs-release-blocking-reports "27.2")

The following command from admin/admin.el sends a reminder message
about release-blocking bugs to the <emacs-devel@gnu.org> mailing list:

  (reminder-for-release-blocking-bugs "27.2")

It is recommended to send this reminder message once a month.  Once the
pretest has started, a reminder message once a week is appropriate.

* TO BE DONE SHORTLY BEFORE RELEASE

See 'admin/make-tarball.txt' for the details of making a release or pretest.

** Make sure the Copyright date reflects the current year in all source files.
(This should be done each January anyway, regardless of releases.)
See admin/update-copyright and admin.el's set-copyright.
For more details, see 'admin/notes/years'.

** Make sure the necessary sources and scripts for any generated files
are included in the source tarball.  (They don't need to be installed,
so e.g. admin/ is fine.)  This is important for legal compliance.

** Remove temporary +++/--- lines in NEWS.
But first make sure there are no unmarked entries, and update the
documentation (or decide no updates are necessary) for those that aren't.

** Try to reorder NEWS: more important things earlier, related items together.

** For a major release, add a "New in Emacs XX" section to efaq.texi.
This should highlight some of the more significant changes.

** cusver-check from admin.el can help find new defcustoms missing
:version tags.  This asks for new and old Lisp directories; use the one
in the current release branch as New and the one from the last released
Emacs version as Old.

Note that this doesn't (yet) know about :package-version and
'customize-package-emacs-version-alist', so it could produce false
positives for packages that use :package-version.  Make sure the files
with defcustoms that use :package-version have the appropriate
add-to-list that determines the correspondence between package versions
and Emacs versions.  Any changes you make in :version etc. should be
tested by running "M-x customize-changed" after regenerating cus-load.el
and loaddefs.el (run "make -C lisp custom-deps autoloads-force").

** Manuals
Check for node names using problematic characters:
  find doc -name '*.texi' -exec grep '^@node[^,]*[:.()]' {} +
Sadly makeinfo does not warn about such characters.

Check for major new features added since the last release (e.g. new
Lisp files), and add the relevant authors to the Acknowledgments in
doc/emacs/ack.texi and emacs.texi.  To find new files, you could run a
command such as this:

  $ git diff --name-status --diff-filter=A emacs-NN emacs-XX

where emacs-NN is the previous Emacs release branch, and emacs-XX is the
new one.

For major releases, rewrite the "Antinews" appendix of the User Manual
(doc/emacs/anti.texi) to describe features lost by downgrading to the
previous version.  The way to do that is read NEWS, pick up the more
significant changes and new features in the upcoming release, then
describe the "benefits" from losing those features.  Be funny, use
humor.  The text written for the previous releases can serve as an example.

Check cross-references between the manuals (e.g. from emacs to elisp)
are correct.  You can use something like the following in the info
directory in the Emacs build tree:

emacs -Q --eval "(progn (require 'info) (setq Info-directory-list '(\".\")))" \
  -f info-xref-check-all

Setting Info-directory-list avoids having system info pages confuse
things.  References to external manuals will be flagged as
uncheckable.  You should still check these, and also that each
external manual has an appropriate redirect in the file manual/.htaccess
in the web pages repository.  E.g.:
Redirect /software/emacs/manual/html_mono/automake.html /software/automake/manual/automake.html
Redirect /software/emacs/manual/html_node/automake/ /software/automake/manual/html_node/

Another tool you can use to check links is gnu.org's linc.py:
https://www.gnu.org/server/source/

You run this with something like:

cd /path/to/cvs/emacs-www
linc.py -o /path/to/output-dir --url https://www.gnu.org/software/emacs/ .

Be warned that it is really, really slow (as in, can take ~ a full day
to check the manual/ directory).  It is probably best to run it on a
single directory at a time from e.g. manual/html_node.  It is very
inefficient, but may reveal a few things that info-xref does not.

make emacs.dvi, elisp.dvi, and deal with any errors (undefined
references etc) in the output.  Break any overfull lines.
Underfull hboxes are not serious, but it can be nice to get rid of
them if a simple rephrasing or rearrangement will work.

Update the master menu and detailed menu (e.g. the antinews version).
The command texinfo-multiple-files-update can do this, but you
probably want to apply the results selectively (e.g. the current master
menu has better line-breaks than the automatic version).  It includes
the menu-entry name (if there is one) as well as the node name - using
only the latter looks better.  Also, it doesn't seem to handle nested
includes, so will miss edebug.texi etc.

Check for widow and orphan lines in the printed manual; make sure all
the pages really look OK in the manual as formatted.  Orphans/widows
are cases where the first/last line of a paragraph is on its own at
the end/start of a page, or where the last word in a paragraph is on
its own at the start of a line.  It looks better if you reword/respace
things to avoid these.  (AFAIK, there is no way to find these except
paging through the whole manual.)  This should be the very last thing
you do, since any change can alter the layout.
(Actually, there is probably little point in trying to do this.
It's only really relevant if printed versions of the manuals are going
to be published.  End-users are not likely to print out all 1000+
pages of the manuals, and even if they do, the resulting page breaks
depend on what paper and font size they use.  This also means that if
you _are_ going to do this, it should be done with the paper and font
size that the GNU Press are going to use when they print the manuals.
I think this is different to what you get if you just use e.g. 'make
emacs.pdf' (e.g., enable "smallbook").

** Check the keybindings in the refcards are correct, and add any new ones.
What paper size are the English versions supposed to be on?
On Debian testing, the packages texlive-lang-czechslovak and
texlive-lang-polish will let you generate the cs-* and sk-* pdfs.
(You may need texlive-lang-cyrillic, texlive-lang-german,
and texlive-fonts-extra for others.)  Gnus refcards need
texlive-latex-extra and/or texlive-latex-recommended.  On Fedora-like
systems, texlive-lh may help.

** Ask maintainers of refcard translations to update them.

Emacs 22 translators:

LANG	Translator            Status
cs	Pavel Janík
de	Sven Joachim
es	Elias Gabriel Perez
fr	Eric Jacoboni
pl	Włodek Bzyl
pt-br	Rodrigo Real
ru	Alex Ott
sk	Miroslav Vaško

** Update some files from their upstream.

Some files in Emacs are copies of data files maintained elsewhere.
Make sure that they are reasonably up-to-date.

- etc/publicsuffix.txt
https://publicsuffix.org/list/public_suffix_list.dat

- leim/SKK-DIC/SKK-JISYO.L
https://raw.githubusercontent.com/skk-dev/dict/master/SKK-JISYO.L

** Check for mistakes in man pages.

The below script checks for any mistakes in the source text of
manual pages.  Fix any errors and re-run the script to verify.

  ./admin/check-man-pages

* DOCUMENTATION

** Check the Emacs Tutorial.

The first line of every tutorial must begin with text ending in a
period (".", ASCII 0x2E) saying "Emacs Tutorial" in the respective
language. This should be followed by "See end for copying conditions",
likewise in the respective language.

After each file name, on the same line or the following line, come the
names of the people who have checked it.

SECTION                  READERS
----------------------------------
TUTORIAL
TUTORIAL.bg
TUTORIAL.cn
TUTORIAL.cs
TUTORIAL.de
TUTORIAL.eo
TUTORIAL.es
TUTORIAL.fr
TUTORIAL.he
TUTORIAL.it
TUTORIAL.ja
TUTORIAL.ko
TUTORIAL.nl
TUTORIAL.pl
TUTORIAL.pt_BR
TUTORIAL.ro
TUTORIAL.ru
TUTORIAL.sk
TUTORIAL.sl
TUTORIAL.sv
TUTORIAL.th
TUTORIAL.zh

* OTHER INFORMATION

For Emacs's versioning scheme, see 'admin/notes/versioning'.

For instructions to create pretest or release tarballs, announcements,
etc., see 'admin/make-tarball.txt'.


Local variables:
mode: outline
coding: utf-8
end:
