release-process 10.5 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 several 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

The 2 main manuals, the User Manual and the Emacs Lisp Manual, need to
be proofread, preferably by at least 2 different persons, and any
uncovered problems fixed.  This is a lot of work, so it is advisable
to divide the job between several people (see the checklist near the
end of this file).

38
In parallel to this phase, 'master' can receive new features, to be
39 40 41 42 43 44 45 46 47 48 49 50 51 52 53
released in the next release cycle.  From time to time, the master
branches merges bugfix commits from the "emacs-NN" branch.

* RELEASE-CRITICAL BUGS

Emacs uses the "blocking bug(s)" feature of Debbugs for bugs need to
be addressed in the next release.

Currently, bug#19759 is the tracking bug for release of 25.1.  Say
bug#123 needs to be fixed for Emacs 25.1.  Send a message to
control@debbugs.gnu.org that says:

   block 19759 by 123

Change "block" to "unblock" to unblock the bug.
54

Luc Teirlinck's avatar
Luc Teirlinck committed
55
* TO BE DONE SHORTLY BEFORE RELEASE
Luc Teirlinck's avatar
Luc Teirlinck committed
56

57
** Make sure the Copyright date reflects the current year in the source
58
files.  See 'admin/notes/years' for information about maintaining
59 60
copyright years for GNU Emacs.

61
** Make sure the necessary sources and scripts for any generated files
62 63 64 65 66 67 68 69 70 71
are included in the source tarball.  (They don't need to be installed,
so e.g. admin/ is fine.)

** Regenerate AUTHORS by using admin/authors.el
(The instructions are at the beginning of that file.)

** 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.
72

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

78 79 80 81
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.

82 83 84 85 86 87 88 89 90
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 major release can serve as
good example.

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

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

97 98 99 100 101 102 103 104
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/

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

108
You run this with something like:
109 110 111 112 113 114

cd /path/to/cvs/emacs-www
linc.py -o /path/to/output-dir --url http://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
115
single directory at a time from e.g. manual/html_node.  It is very
116 117
inefficient, but may reveal a few things that info-xref does not.

Glenn Morris's avatar
Glenn Morris committed
118 119 120 121 122
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.

123
Update the master menu and detailed menu (e.g. the antinews version).
Glenn Morris's avatar
Glenn Morris committed
124
The command texinfo-multiple-files-update can do this, but you
125
probably want to apply the results selectively (e.g. the current master
Glenn Morris's avatar
Glenn Morris committed
126 127 128 129 130
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
131
Check for widow and orphan lines in the printed manual; make sure all
132
the pages really look OK in the manual as formatted.  Orphans/widows
Glenn Morris's avatar
Glenn Morris committed
133 134 135 136 137 138
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
139 140 141 142 143 144 145
(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.
146
I think this is different to what you get if you just use e.g. 'make
Glenn Morris's avatar
Glenn Morris committed
147
emacs.pdf' (e.g., enable "smallbook").
148

149 150 151 152
** 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.

Glenn Morris's avatar
Glenn Morris committed
153 154
** 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
155 156
On Debian testing, the packages texlive-lang-czechslovak and
texlive-lang-polish will let you generate the cs-* and sk-* pdfs.
Glenn Morris's avatar
Glenn Morris committed
157
(You may need texlive-lang-cyrillic, texlive-lang-german for others.)
Glenn Morris's avatar
Glenn Morris committed
158 159
The Makefile rules did not work for me, I had to use something like:
csplain -output-format=pdf cs-refcard
Glenn Morris's avatar
Glenn Morris committed
160

161 162
** Ask maintainers of refcard translations to update them.

Glenn Morris's avatar
Glenn Morris committed
163
Emacs 22 translators:
164 165

LANG	Translator            Status
166 167 168 169 170 171 172
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
173

Glenn Morris's avatar
Glenn Morris committed
174
** cusver-check from admin.el can help find new defcustoms missing
Glenn Morris's avatar
Glenn Morris committed
175 176
:version tags.

Paul Eggert's avatar
Paul Eggert committed
177 178
** Add a line to etc/HISTORY for the release version number and date.

179 180
* BUGS

181 182 183
** 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:

184
1. Gnus binds 'M-s' to 'gnus-summary-search-article-forward'.
185

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

189 190 191 192
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').
193

194 195 196
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.
197

198
5. Rmail binds '\es' to 'rmail-search'/'rmail-summary-search'.
199 200


201
* DOCUMENTATION
202

203 204
** Check the Emacs Tutorial.

205 206
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
207 208
language. This should be followed by "See end for copying conditions",
likewise in the respective language.
209 210 211 212

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

213 214
SECTION                  READERS
----------------------------------
215 216 217
TUTORIAL
TUTORIAL.bg
TUTORIAL.cn
218
TUTORIAL.cs
219
TUTORIAL.de
220
TUTORIAL.eo
221 222
TUTORIAL.es
TUTORIAL.fr
223
TUTORIAL.he
224 225
TUTORIAL.it
TUTORIAL.ja
226
TUTORIAL.ko
227
TUTORIAL.nl
228 229
TUTORIAL.pl
TUTORIAL.pt_BR
230
TUTORIAL.ro
231
TUTORIAL.ru
232
TUTORIAL.sk
233 234
TUTORIAL.sl
TUTORIAL.sv
235
TUTORIAL.th
236
TUTORIAL.zh
237

Chong Yidong's avatar
Chong Yidong committed
238 239
** Check the manual.

240 241 242 243 244 245 246 247 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
abbrevs.texi
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
292 293 294

** Check the Lisp manual.

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

345 346
* OTHER INFORMATION

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

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

Kim F. Storm's avatar
Kim F. Storm committed
352 353 354

Local variables:
mode: outline
355
coding: utf-8
Kim F. Storm's avatar
Kim F. Storm committed
356
end: