release-process 10.9 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 102

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

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

109 110 111 112 113 114 115 116
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/

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

120
You run this with something like:
121 122

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

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

Glenn Morris's avatar
Glenn Morris committed
130 131 132 133 134
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.

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

Glenn Morris's avatar
Glenn Morris committed
161 162
** 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
163 164
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
165
(You may need texlive-lang-cyrillic, texlive-lang-german for others.)
Glenn Morris's avatar
Glenn Morris committed
166 167
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
168

169 170
** Ask maintainers of refcard translations to update them.

Glenn Morris's avatar
Glenn Morris committed
171
Emacs 22 translators:
172 173

LANG	Translator            Status
174 175 176 177 178 179 180
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
181

182 183
* BUGS

184 185 186
** 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:

187
1. Gnus binds 'M-s' to 'gnus-summary-search-article-forward'.
188

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

192 193 194 195
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').
196

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

201
5. Rmail binds '\es' to 'rmail-search'/'rmail-summary-search'.
202 203


204
* DOCUMENTATION
205

206 207
** Check the Emacs Tutorial.

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

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

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

Chong Yidong's avatar
Chong Yidong committed
241 242
** Check the manual.

243
abbrevs.texi 		Steve Byrne
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 292 293 294
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
295 296 297

** Check the Lisp manual.

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

348 349
* OTHER INFORMATION

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

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

Kim F. Storm's avatar
Kim F. Storm committed
355 356 357

Local variables:
mode: outline
358
coding: utf-8
Kim F. Storm's avatar
Kim F. Storm committed
359
end: