release-process 11 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#21966 is the tracking bug for release of 25.2 and
bug#24655 is the tracking bug for release 26.1.  Say bug#123 needs
to be fixed for Emacs 26.1.  Send a message to control@debbugs.gnu.org
52
that says:
53

54
   block 24655 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

Luc Teirlinck's avatar
Luc Teirlinck committed
62
* TO BE DONE SHORTLY BEFORE RELEASE
Luc Teirlinck's avatar
Luc Teirlinck committed
63

64 65 66 67 68 69
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'.
70

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

** Remove temporary +++/--- lines in NEWS.
But first make sure there are no unmarked entries, and update the
77 78 79 80 81 82 83 84 85
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
86
** Manuals
87 88 89 90
Check for node names using problematic characters:
  find doc -name '*.texi' -exec grep '^@node[^,]*[:.()]' {} +
Sadly makeinfo does not warn about such characters.

91 92 93 94
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.

95 96 97 98 99
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
100
humor.  The text written for the previous releases can serve as an example.
101

Eli Zaretskii's avatar
Eli Zaretskii committed
102 103 104 105
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.

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

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

113 114 115 116 117 118 119 120
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/

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

124
You run this with something like:
125 126

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

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

Glenn Morris's avatar
Glenn Morris committed
134 135 136 137 138
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.

139
Update the master menu and detailed menu (e.g. the antinews version).
Glenn Morris's avatar
Glenn Morris committed
140
The command texinfo-multiple-files-update can do this, but you
141
probably want to apply the results selectively (e.g. the current master
Glenn Morris's avatar
Glenn Morris committed
142 143 144 145 146
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
147
Check for widow and orphan lines in the printed manual; make sure all
148
the pages really look OK in the manual as formatted.  Orphans/widows
Glenn Morris's avatar
Glenn Morris committed
149 150 151 152 153 154
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
155 156 157 158 159 160 161
(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.
162
I think this is different to what you get if you just use e.g. 'make
Glenn Morris's avatar
Glenn Morris committed
163
emacs.pdf' (e.g., enable "smallbook").
164

Glenn Morris's avatar
Glenn Morris committed
165 166
** 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
167 168
On Debian testing, the packages texlive-lang-czechslovak and
texlive-lang-polish will let you generate the cs-* and sk-* pdfs.
169 170 171
(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
172

173 174
** Ask maintainers of refcard translations to update them.

Glenn Morris's avatar
Glenn Morris committed
175
Emacs 22 translators:
176 177

LANG	Translator            Status
178 179 180 181 182 183 184
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
185

186 187
* BUGS

188 189 190
** 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:

191
1. Gnus binds 'M-s' to 'gnus-summary-search-article-forward'.
192

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

196 197 198 199
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').
200

201 202 203
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.
204

205
5. Rmail binds '\es' to 'rmail-search'/'rmail-summary-search'.
206 207


208
* DOCUMENTATION
209

210 211
** Check the Emacs Tutorial.

212 213
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
214 215
language. This should be followed by "See end for copying conditions",
likewise in the respective language.
216 217 218 219

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

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

Chong Yidong's avatar
Chong Yidong committed
245 246
** Check the manual.

247
abbrevs.texi 		Steve Byrne
248 249 250 251 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
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
299 300 301

** Check the Lisp manual.

302
abbrevs.texi 		Steve Byrne
303 304 305 306 307 308 309 310 311 312 313
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
314
elisp.texi
315 316 317 318 319 320 321 322
errors.texi
eval.texi
files.texi
frames.texi
functions.texi
hash.texi
help.texi
hooks.texi
Chong Yidong's avatar
Chong Yidong committed
323
index.texi
324 325 326 327 328 329 330 331 332 333 334
internals.texi
intro.texi
keymaps.texi
lists.texi
loading.texi
macros.texi
maps.texi
markers.texi
minibuf.texi
modes.texi
nonascii.texi
335
numbers.texi
336 337 338 339 340 341 342 343 344 345 346 347 348 349 350
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
351

352 353
* OTHER INFORMATION

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

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

Kim F. Storm's avatar
Kim F. Storm committed
359 360 361

Local variables:
mode: outline
362
coding: utf-8
Kim F. Storm's avatar
Kim F. Storm committed
363
end: