release-process 11.2 KB
Newer Older
1 2 3 4 5 6 7 8 9
This document describes the release process used by GNU Emacs.

* RELEASE CYCLE

Each release cycle will be split into two periods.

** Phase one: development

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
11 12
branches.

13
** Phase two: fixing and stabilizing the release branch
14 15 16 17 18

Shortly before 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.

19 20
This phase is mostly spent fixing bugs and documenting new features
and changes on the "emacs-NN" branch.  Actually, the default branch
21 22
for pushing any work in this phase should be "emacs-NN", except for
new features.
23

24 25
At the beginning of this phase, a release branch called "emacs-NN"
("NN" represents the major version number of the new Emacs release)
26 27
will be cut from 'master'.  When that happens, the version number on
'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 30
'master'.  For major releases, also update the value of
'customize-changed-options-previous-release'.
31

32 33 34 35 36 37
Each chapter of the two main manuals, the User Manual and the Emacs
Lisp Manual, should be proofread, preferably by at least two people.
This job is so big that it should be considered a collective
responsibility, not fobbed off on just a few people.  After each
chapter is checked, mark off the name(s) of those who checked it in
the checklist near the end of this file.
38

39
In parallel to this phase, 'master' can receive new features, to be
40 41
released in the next release cycle.  From time to time, the master
branches merges bugfix commits from the "emacs-NN" branch.
42
See admin/gitmerge.el.
43 44 45

* RELEASE-CRITICAL BUGS

46 47
Emacs uses the "blocking" feature of Debbugs for bugs that need to be
addressed in the next release.
48

49 50 51
Currently, bug#39200 is the tracking bug for release of 27.1 and
bug#39202 is the tracking bug for release 28.1.  Say bug#123 needs
to be fixed for Emacs 27.1.  Send a message to control@debbugs.gnu.org
52
that says:
53

54
   block 39200 by 123
55

56 57 58 59 60
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.

61 62 63 64
If you use the debbugs package from GNU ELPA, you can apply the
following form to see all bugs which block a given release:

  (debbugs-gnu-emacs-release-blocking-reports "27.1")
65

Luc Teirlinck's avatar
Luc Teirlinck committed
66
* TO BE DONE SHORTLY BEFORE RELEASE
Luc Teirlinck's avatar
Luc Teirlinck committed
67

68 69 70 71 72 73
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'.
74

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

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

** Try to reorder NEWS: most important things first, related items together.

** For a major release, add a "New in Emacs XX" section to faq.texi.

** cusver-check from admin.el can help find new defcustoms missing
:version tags.

Glenn Morris's avatar
Glenn Morris committed
90
** Manuals
91 92 93 94
Check for node names using problematic characters:
  find doc -name '*.texi' -exec grep '^@node[^,]*[:.()]' {} +
Sadly makeinfo does not warn about such characters.

95 96 97 98
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.

99 100 101 102 103
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
104
humor.  The text written for the previous releases can serve as an example.
105

Eli Zaretskii's avatar
Eli Zaretskii committed
106 107 108 109
The Emacs FAQ (doc/misc/efaq.texi) also has a "What's new" section;
for major releases a new section should be added listing the
significant changes.

110
Check cross-references between the manuals (e.g. from emacs to elisp)
Glenn Morris's avatar
Glenn Morris committed
111 112 113
are correct.  You can use something like the following in the info
directory in the Emacs build tree:

114
emacs -Q --eval "(progn (require 'info) (setq Info-directory-list '(\".\")))" \
Glenn Morris's avatar
Glenn Morris committed
115
  -f info-xref-check-all
Glenn Morris's avatar
Glenn Morris committed
116

117 118 119 120 121 122 123 124
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/

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

128
You run this with something like:
129 130

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

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
135
single directory at a time from e.g. manual/html_node.  It is very
136 137
inefficient, but may reveal a few things that info-xref does not.

Glenn Morris's avatar
Glenn Morris committed
138 139 140 141 142
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.

143
Update the master menu and detailed menu (e.g. the antinews version).
Glenn Morris's avatar
Glenn Morris committed
144
The command texinfo-multiple-files-update can do this, but you
145
probably want to apply the results selectively (e.g. the current master
Glenn Morris's avatar
Glenn Morris committed
146 147 148 149 150
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.

Glenn Morris's avatar
Glenn Morris committed
151
Check for widow and orphan lines in the printed manual; make sure all
152
the pages really look OK in the manual as formatted.  Orphans/widows
Glenn Morris's avatar
Glenn Morris committed
153 154 155 156 157 158
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.
Glenn Morris's avatar
Glenn Morris committed
159 160 161 162 163 164 165
(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.
166
I think this is different to what you get if you just use e.g. 'make
Glenn Morris's avatar
Glenn Morris committed
167
emacs.pdf' (e.g., enable "smallbook").
168

Glenn Morris's avatar
Glenn Morris committed
169 170
** Check the keybindings in the refcards are correct, and add any new ones.
What paper size are the English versions supposed to be on?
Glenn Morris's avatar
Glenn Morris committed
171 172
On Debian testing, the packages texlive-lang-czechslovak and
texlive-lang-polish will let you generate the cs-* and sk-* pdfs.
173 174 175
(You may need texlive-lang-cyrillic, texlive-lang-german,
and texlive-fonts-extra for others.)  On Fedora-like systems,
texlive-lh may help.
Glenn Morris's avatar
Glenn Morris committed
176

177 178
** Ask maintainers of refcard translations to update them.

Glenn Morris's avatar
Glenn Morris committed
179
Emacs 22 translators:
180 181

LANG	Translator            Status
182 183 184 185 186 187 188
cs	Pavel Janík
de	Sven Joachim
fr	Eric Jacoboni
pl	Włodek Bzyl
pt-br	Rodrigo Real
ru	Alex Ott
sk	Miroslav Vaško
189

190 191
* BUGS

192 193 194
** Check for modes which bind M-s that conflicts with a new global binding M-s
and change key bindings where necessary.  The current list of modes:

195
1. Gnus binds 'M-s' to 'gnus-summary-search-article-forward'.
196

197
2. Minibuffer binds 'M-s' to 'next-matching-history-element'
198 199
   (not useful any more since C-s can now search in the history).

200 201 202 203
3. 'center-line' in Text mode was already moved to the text formatting
   keymap as 'M-o M-s' (thus this binding is not necessary any more
   in 'nroff-mode-map' too and can be removed now from the nroff mode
   because it can now use the global key binding 'M-o M-s' 'center-line').
204

205 206 207
4. PCL-CVS binds 'M-s' to 'cvs-status', and log-edit-mode binds it to
   'log-edit-comment-search-forward'.  Perhaps search commands
   on the global key binding 'M-s' are useless in these modes.
208

209
5. Rmail binds '\es' to 'rmail-search'/'rmail-summary-search'.
210 211


212
* DOCUMENTATION
213

214 215
** Check the Emacs Tutorial.

216 217
The first line of every tutorial must begin with text ending in a
period (".", ASCII 0x2E) saying "Emacs Tutorial" in the respective
Glenn Morris's avatar
Glenn Morris committed
218 219
language. This should be followed by "See end for copying conditions",
likewise in the respective language.
220 221 222 223

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

224 225
SECTION                  READERS
----------------------------------
226 227 228
TUTORIAL
TUTORIAL.bg
TUTORIAL.cn
229
TUTORIAL.cs
230
TUTORIAL.de
231
TUTORIAL.eo
232 233
TUTORIAL.es
TUTORIAL.fr
234
TUTORIAL.he
235 236
TUTORIAL.it
TUTORIAL.ja
237
TUTORIAL.ko
238
TUTORIAL.nl
239 240
TUTORIAL.pl
TUTORIAL.pt_BR
241
TUTORIAL.ro
242
TUTORIAL.ru
243
TUTORIAL.sk
244 245
TUTORIAL.sl
TUTORIAL.sv
246
TUTORIAL.th
247
TUTORIAL.zh
248

Chong Yidong's avatar
Chong Yidong committed
249 250
** Check the manual.

251
abbrevs.texi 		Steve Byrne
252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302
ack.texi
anti.texi
arevert-xtra.texi
basic.texi
buffers.texi
building.texi
calendar.texi
cal-xtra.texi
cmdargs.texi
commands.texi
custom.texi
dired.texi
dired-xtra.texi
display.texi
emacs.texi
emacs-xtra.texi
emerge-xtra.texi
entering.texi
files.texi
fixit.texi
fortran-xtra.texi
frames.texi
glossary.texi
help.texi
indent.texi
killing.texi
kmacro.texi
macos.texi
maintaining.texi
mark.texi
mini.texi
misc.texi
modes.texi
msdos.texi
msdos-xtra.texi
mule.texi
m-x.texi
package.texi
picture-xtra.texi
programs.texi
regs.texi
rmail.texi
screen.texi
search.texi
sending.texi
text.texi
trouble.texi
vc-xtra.texi
vc1-xtra.texi
windows.texi
xresources.texi
Chong Yidong's avatar
Chong Yidong committed
303 304 305

** Check the Lisp manual.

306
abbrevs.texi 		Steve Byrne
307 308 309 310 311 312 313 314 315 316 317
anti.texi
back.texi
backups.texi
buffers.texi
commands.texi
compile.texi
control.texi
customize.texi
debugging.texi
display.texi
edebug.texi
Chong Yidong's avatar
Chong Yidong committed
318
elisp.texi
319 320 321 322 323 324 325 326
errors.texi
eval.texi
files.texi
frames.texi
functions.texi
hash.texi
help.texi
hooks.texi
Chong Yidong's avatar
Chong Yidong committed
327
index.texi
328 329 330 331 332 333 334 335 336 337 338
internals.texi
intro.texi
keymaps.texi
lists.texi
loading.texi
macros.texi
maps.texi
markers.texi
minibuf.texi
modes.texi
nonascii.texi
339
numbers.texi
340 341 342 343 344 345 346 347 348 349 350 351 352 353 354
objects.texi
os.texi
package.texi
positions.texi
processes.texi
searching.texi
sequences.texi
streams.texi
strings.texi
symbols.texi
syntax.texi
text.texi
tips.texi
variables.texi
windows.texi
Chong Yidong's avatar
Chong Yidong committed
355

356 357
* OTHER INFORMATION

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

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

Kim F. Storm's avatar
Kim F. Storm committed
363 364 365

Local variables:
mode: outline
366
coding: utf-8
Kim F. Storm's avatar
Kim F. Storm committed
367
end: