1 This document describes the release process used by GNU Emacs.
5 Each release cycle will be split into two periods.
7 ** Phase one: development
9 The first phase of the release schedule is the "heads-down" working
10 period for new features, on the 'master' branch and any needed feature
13 ** Phase two: fixing and stabilizing the release branch
15 Shortly before this phase, Emacs developers will be devoted to
16 figuring out what features to include in the next release and what
17 features to defer to a later release.
19 This phase is mostly spent fixing bugs and documenting new features
20 and changes on the "emacs-NN" branch. Actually, the default branch
21 for pushing any work in this phase should be "emacs-NN", except for
24 At the beginning of this phase, a release branch called "emacs-NN"
25 ("NN" represents the major version number of the new Emacs release)
26 will be cut from 'master'. When that happens, the version number on
27 'master' should be incremented; use admin/admin.el's 'set-version'
28 command to do that, then commit the changes it made and push to
29 'master'. For major releases, also update the value of
30 'customize-changed-options-previous-release'.
32 Each chapter of the two main manuals, the User Manual and the Emacs
33 Lisp Manual, should be proofread, preferably by at least two people.
34 This job is so big that it should be considered a collective
35 responsibility, not fobbed off on just a few people. After each
36 chapter is checked, mark off the name(s) of those who checked it in
37 the checklist near the end of this file.
39 In parallel to this phase, 'master' can receive new features, to be
40 released in the next release cycle. From time to time, the master
41 branches merges bugfix commits from the "emacs-NN" branch.
42 See admin/gitmerge.el.
44 * RELEASE-BLOCKING BUGS
46 Emacs uses the "blocking" feature of Debbugs for bugs that need to be
47 addressed in the next release.
49 Currently, bug#43018 is the tracking bug for release of 27.2 and
50 bug#39202 is the tracking bug for release 28.1. Say bug#123 needs
51 to be fixed for Emacs 27.2. Send a message to control@debbugs.gnu.org
56 Change "block" to "unblock" to remove a bug from the list. Closed
57 bugs are not listed as blockers, so you do not need to explicitly
58 unblock one that has been closed. You may need to force an update of
59 the tracking bug with ctrl-f5/shift-reload to see the latest version.
61 If you use the debbugs package from GNU ELPA, you can apply the
62 following command to see all bugs which block a given release:
64 (debbugs-gnu-emacs-release-blocking-reports "27.2")
66 The following command from admin/admin.el sends a reminder message
67 about release-blocking bugs to the <emacs-devel@gnu.org> mailing list:
69 (reminder-for-release-blocking-bugs "27.2")
71 It is recommended to send this reminder message once a month. Once the
72 pretest has started, a reminder message once a week is appropriate.
74 * TO BE DONE SHORTLY BEFORE RELEASE
76 See 'admin/make-tarball.txt' for the details of making a release or pretest.
78 ** Make sure the Copyright date reflects the current year in all source files.
79 (This should be done each January anyway, regardless of releases.)
80 See admin/update-copyright and admin.el's set-copyright.
81 For more details, see 'admin/notes/years'.
83 ** Make sure the necessary sources and scripts for any generated files
84 are included in the source tarball. (They don't need to be installed,
85 so e.g. admin/ is fine.) This is important for legal compliance.
87 ** Remove temporary +++/--- lines in NEWS.
88 But first make sure there are no unmarked entries, and update the
89 documentation (or decide no updates are necessary) for those that aren't.
91 ** Try to reorder NEWS: most important things first, related items together.
93 ** For a major release, add a "New in Emacs XX" section to faq.texi.
95 ** cusver-check from admin.el can help find new defcustoms missing
99 Check for node names using problematic characters:
100 find doc -name '*.texi' -exec grep '^@node[^,]*[:.()]' {} +
101 Sadly makeinfo does not warn about such characters.
103 Check for major new features added since the last release (e.g. new
104 lisp files), and add the relevant authors to the Acknowledgments in
105 doc/emacs/ack.texi and emacs.texi.
107 For major releases, rewrite the "Antinews" appendix of the User Manual
108 (doc/emacs/anti.texi) to describe features lost by downgrading to the
109 previous version. The way to do that is read NEWS, pick up the more
110 significant changes and new features in the upcoming release, then
111 describe the "benefits" from losing those features. Be funny, use
112 humor. The text written for the previous releases can serve as an example.
114 The Emacs FAQ (doc/misc/efaq.texi) also has a "What's new" section;
115 for major releases a new section should be added listing the
118 Check cross-references between the manuals (e.g. from emacs to elisp)
119 are correct. You can use something like the following in the info
120 directory in the Emacs build tree:
122 emacs -Q --eval "(progn (require 'info) (setq Info-directory-list '(\".\")))" \
123 -f info-xref-check-all
125 Setting Info-directory-list avoids having system info pages confuse
126 things. References to external manuals will be flagged as
127 uncheckable. You should still check these, and also that each
128 external manual has an appropriate redirect in the file manual/.htaccess
129 in the web pages repository. E.g.:
130 Redirect /software/emacs/manual/html_mono/automake.html /software/automake/manual/automake.html
131 Redirect /software/emacs/manual/html_node/automake/ /software/automake/manual/html_node/
133 Another tool you can use to check links is gnu.org's linc.py:
134 https://www.gnu.org/server/source/
136 You run this with something like:
138 cd /path/to/cvs/emacs-www
139 linc.py -o /path/to/output-dir --url https://www.gnu.org/software/emacs/ .
141 Be warned that it is really, really slow (as in, can take ~ a full day
142 to check the manual/ directory). It is probably best to run it on a
143 single directory at a time from e.g. manual/html_node. It is very
144 inefficient, but may reveal a few things that info-xref does not.
146 make emacs.dvi, elisp.dvi, and deal with any errors (undefined
147 references etc) in the output. Break any overfull lines.
148 Underfull hboxes are not serious, but it can be nice to get rid of
149 them if a simple rephrasing or rearrangement will work.
151 Update the master menu and detailed menu (e.g. the antinews version).
152 The command texinfo-multiple-files-update can do this, but you
153 probably want to apply the results selectively (e.g. the current master
154 menu has better line-breaks than the automatic version). It includes
155 the menu-entry name (if there is one) as well as the node name - using
156 only the latter looks better. Also, it doesn't seem to handle nested
157 includes, so will miss edebug.texi etc.
159 Check for widow and orphan lines in the printed manual; make sure all
160 the pages really look OK in the manual as formatted. Orphans/widows
161 are cases where the first/last line of a paragraph is on its own at
162 the end/start of a page, or where the last word in a paragraph is on
163 its own at the start of a line. It looks better if you reword/respace
164 things to avoid these. (AFAIK, there is no way to find these except
165 paging through the whole manual.) This should be the very last thing
166 you do, since any change can alter the layout.
167 (Actually, there is probably little point in trying to do this.
168 It's only really relevant if printed versions of the manuals are going
169 to be published. End-users are not likely to print out all 1000+
170 pages of the manuals, and even if they do, the resulting page breaks
171 depend on what paper and font size they use. This also means that if
172 you _are_ going to do this, it should be done with the paper and font
173 size that the GNU Press are going to use when they print the manuals.
174 I think this is different to what you get if you just use e.g. 'make
175 emacs.pdf' (e.g., enable "smallbook").
177 ** Check the keybindings in the refcards are correct, and add any new ones.
178 What paper size are the English versions supposed to be on?
179 On Debian testing, the packages texlive-lang-czechslovak and
180 texlive-lang-polish will let you generate the cs-* and sk-* pdfs.
181 (You may need texlive-lang-cyrillic, texlive-lang-german,
182 and texlive-fonts-extra for others.) Gnus refcards need
183 texlive-latex-extra and/or texlive-latex-recommended. On Fedora-like
184 systems, texlive-lh may help.
186 ** Ask maintainers of refcard translations to update them.
188 Emacs 22 translators:
190 LANG Translator Status
199 ** Update some files from their upstream.
201 Some files in Emacs are copies of data files maintained elsewhere.
202 Make sure that they are reasonably up-to-date.
204 - etc/publicsuffix.txt
205 https://publicsuffix.org/list/public_suffix_list.dat
207 - leim/SKK-DIC/SKK-JISYO.L
208 https://raw.githubusercontent.com/skk-dev/dict/master/SKK-JISYO.L
212 ** Check for modes which bind M-s that conflicts with a new global binding M-s
213 and change key bindings where necessary. The current list of modes:
215 1. Minibuffer binds 'M-s' to 'next-matching-history-element'
216 (not useful any more since C-s can now search in the history).
218 2. PCL-CVS binds 'M-s' to 'cvs-status', and log-edit-mode binds it to
219 'log-edit-comment-search-forward'. Perhaps search commands
220 on the global key binding 'M-s' are useless in these modes.
222 3. Rmail binds '\es' to 'rmail-search'/'rmail-summary-search'.
227 ** Check the Emacs Tutorial.
229 The first line of every tutorial must begin with text ending in a
230 period (".", ASCII 0x2E) saying "Emacs Tutorial" in the respective
231 language. This should be followed by "See end for copying conditions",
232 likewise in the respective language.
234 After each file name, on the same line or the following line, come the
235 names of the people who have checked it.
238 ----------------------------------
264 abbrevs.texi Steve Byrne
317 ** Check the Lisp manual.
319 abbrevs.texi Steve Byrne
371 For Emacs's versioning scheme, see 'admin/notes/versioning'.
373 For instructions to create pretest or release tarballs, announcements,
374 etc., see 'admin/make-tarball.txt'.