-
Notifications
You must be signed in to change notification settings - Fork 11
/
CONTRIBUTE
385 lines (292 loc) · 16.2 KB
/
CONTRIBUTE
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
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
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
* How developers contribute to GNU Emacs
Here is how software developers can contribute to Emacs. (Non-developers: see
https://www.gnu.org/software/emacs/manual/html_node/emacs/Contributing.html
or run the shell command 'info "(emacs)Contributing"'.)
** The Emacs repository
Emacs development uses Git on Savannah for its main repository.
Briefly, the following shell commands build and run Emacs from scratch:
git config --global user.name 'Your Name'
git config --global user.email '[email protected]'
git config --global transfer.fsckObjects true
git clone git://git.sv.gnu.org/emacs.git
cd emacs
./autogen.sh
./configure
make
src/emacs
For more details, see
http://www.emacswiki.org/emacs/GitQuickStartForEmacsDevs and
http://www.emacswiki.org/emacs/GitForEmacsDevs or see the file
admin/notes/git-workflow.
** Getting involved with development
Discussion about Emacs development takes place on [email protected].
You can subscribe to the [email protected] mailing list.
If you want to get only the important mails (for things like
feature freezes), choose to receive only the 'emacs-announce' topic
(although so far this feature has not been well or consistently used).
See https://lists.gnu.org/mailman/listinfo/emacs-devel for mailing list
instructions and archives. You can develop and commit changes in your
own copy of the repository, and discuss proposed changes on the
mailing list. Frequent contributors to Emacs can request write access
there.
Bug reports and fixes, feature requests and patches/implementations
should be sent to [email protected], the bug/feature list. This
is coupled to the https://debbugs.gnu.org tracker. It is best to use
the command 'M-x report-emacs-bug RET' to report issues to the tracker
(described below). Be prepared to receive comments and requests for
changes in your patches, following your submission.
The Savannah info page https://savannah.gnu.org/mail/?group=emacs
describes how to subscribe to the mailing lists, or see the list
archives.
To email a patch you can use a shell command like 'git format-patch -1'
to create a file, and then attach the file to your email. This nicely
packages the patch's commit message and changes. To send just one
such patch without additional remarks, you can use a command like
'git send-email [email protected] 0001-DESCRIPTION.patch'.
** Issue tracker (a.k.a. "bug tracker")
The Emacs issue tracker at https://debbugs.gnu.org lets you view bug
reports and search the database for bugs matching several criteria.
Messages posted to the [email protected] mailing list, mentioned
above, are recorded by the tracker with the corresponding bugs/issues.
GNU ELPA has a 'debbugs' package that allows accessing the tracker
database from Emacs.
Bugs needs regular attention. A large backlog of bugs is
disheartening to the developers, and a culture of ignoring bugs is
harmful to users, who expect software that works. Bugs have to be
regularly looked at and acted upon. Not all bugs are critical, but at
the least, each bug needs to be regularly re-reviewed to make sure it
is still reproducible.
The process of going through old or new bugs and acting on them is
called bug triage. This process is described in the file
admin/notes/bug-triage.
** Documenting your changes
Any change that matters to end-users should have an entry in etc/NEWS.
Doc-strings should be updated together with the code.
Think about whether your change requires updating the manuals. If you
know it does not, mark the NEWS entry with "---". If you know
that *all* the necessary documentation updates have been made as part
of your changes or those by others, mark the entry with "+++".
Otherwise do not mark it.
If your change requires updating the manuals to document new
functions/commands/variables/faces, then use the proper Texinfo
command to index them; for instance, use @vindex for variables and
@findex for functions/commands. For the full list of predefine indices, see
https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Predefined-Indices.html
or run the shell command 'info "(texinfo)Predefined Indices"'.
We prefer American English both in doc strings and in the manuals.
That includes both spelling (e.g., "behavior", not "behaviour") and
the convention of leaving 2 spaces between sentences.
For more specific tips on Emacs's doc style, see
https://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tips.html
Use 'checkdoc' to check for documentation errors before submitting a patch.
** Testing your changes
Please test your changes before committing them or sending them to the
list. If possible, add a new test along with any bug fix or new
functionality you commit (of course, some changes cannot be easily
tested).
Emacs uses ERT, Emacs Lisp Regression Testing, for testing. See
https://www.gnu.org/software/emacs/manual/html_node/ert/
or run 'info "(ert)"' for more information on writing and running
tests.
If your test lasts longer than some few seconds, mark it in its
'ert-deftest' definition with ":tags '(:expensive-test)".
To run tests on the entire Emacs tree, run "make check" from the
top-level directory. Most tests are in the directory "test/". From
the "test/" directory, run "make <filename>" to run the tests for
<filename>.el(c). See "test/README" for more information.
** Commit messages
Ordinarily, a change you commit should contain a log entry in its
commit message and should not touch the repository's ChangeLog files.
Here is an example commit message (indented):
Deactivate shifted region
Do not silently extend a region that is not highlighted;
this can happen after a shift (Bug#19003).
* doc/emacs/mark.texi (Shift Selection): Document the change.
* lisp/window.el (handle-select-window):
* src/frame.c (Fhandle_switch_frame, Fselected_frame):
Deactivate the mark.
Occasionally, commit messages are collected and prepended to a
ChangeLog file, where they can be corrected. It saves time to get
them right the first time, so here are guidelines for formatting them:
- Start with a single unindented summary line explaining the change;
do not end this line with a period. If that line starts with a
semicolon and a space "; ", the commit message will be ignored when
generating the ChangeLog file. Use this for minor commits that do
not need separate ChangeLog entries, such as changes in etc/NEWS.
- After the summary line, there should be an empty line, then
unindented ChangeLog entries.
- Limit lines in commit messages to 78 characters, unless they consist
of a single word of at most 140 characters; this is enforced by a
commit hook. It's nicer to limit the summary line to 50 characters;
this isn't enforced. If the change can't be summarized so briefly,
add a paragraph after the empty line and before the individual file
descriptions.
- If only a single file is changed, the summary line can be the normal
file first line (starting with the asterisk). Then there is no
individual files section.
- If the commit has more than one author, the commit message should
contain separate lines to mention the other authors, like the
following:
Co-authored-by: Joe Schmoe <[email protected]>
- If the commit is a tiny change that is exempt from copyright paperwork,
the commit message should contain a separate line like the following:
Copyright-paperwork-exempt: yes
- The commit message should contain "Bug#NNNNN" if it is related to
bug number NNNNN in the debbugs database. This string is often
parenthesized, as in "(Bug#19003)".
- When citing URLs, prefer https: to http: when either will do. In
particular, gnu.org and fsf.org URLs should start with "https:".
- Commit messages should contain only printable UTF-8 characters.
- Commit messages should not contain the "Signed-off-by:" lines that
are used in some other projects.
- Any lines of the commit message that start with "; " are omitted
from the generated ChangeLog.
- Explaining the rationale for a design choice is best done in comments
in the source code. However, sometimes it is useful to describe just
the rationale for a change; that can be done in the commit message
between the summary line and the file entries.
- Emacs generally follows the GNU coding standards for ChangeLogs: see
https://www.gnu.org/prep/standards/html_node/Change-Logs.html
or run 'info "(standards)Change Logs"'. One exception is that
commits still sometimes quote `like-this' (as the standards used to
recommend) rather than 'like-this' or ‘like this’ (as they do now),
as `...' is so widely used elsewhere in Emacs.
- Some commenting rules in the GNU coding standards also apply
to ChangeLog entries: they must be in English, and be complete
sentences starting with a capital and ending with a period (except
the summary line should not end in a period). See
https://www.gnu.org/prep/standards/html_node/Comments.html
or run 'info "(standards)Comments"'. American English is preferred
in Emacs; that includes spelling and leaving 2 blanks between
sentences.
They are preserved indefinitely, and have a reasonable chance of
being read in the future, so it's better that they have good
presentation.
- Use the present tense; describe "what the change does", not "what
the change did".
- Preferred form for several entries with the same content:
* lisp/menu-bar.el (clipboard-yank, clipboard-kill-ring-save)
(clipboard-kill-region):
* lisp/eshell/esh-io.el (eshell-virtual-targets)
(eshell-clipboard-append):
Replace option gui-select-enable-clipboard with
select-enable-clipboard; renamed October 2014. (Bug#25145)
(Rather than anything involving "ditto" and suchlike.)
- There is no standard or recommended way to identify revisions in
ChangeLog entries. Using Git SHA1 values limits the usability of
the references to Git, and will become much less useful if Emacs
switches to a different VCS. So we recommend against that.
One way to identify revisions is by quoting their summary line.
Another is with an action stamp - an RFC3339 date followed by !
followed by the committer's email - for example,
"2014-01-16T05:43:[email protected]". Often, "my previous commit"
will suffice.
- There is no need to mention files such as NEWS and MAINTAINERS, or
to indicate regeneration of files such as 'lib/gnulib.mk', in the
ChangeLog entry. "There is no need" means you don't have to, but
you can if you want to.
** Generating ChangeLog entries
- You can use Emacs functions to write ChangeLog entries; see
https://www.gnu.org/software/emacs/manual/html_node/emacs/Change-Log-Commands.html
or run 'info "(emacs)Change Log Commands"'.
- If you use Emacs VC, one way to format ChangeLog entries is to create
a top-level ChangeLog file manually, and update it with 'C-x 4 a' as
usual. Do not register the ChangeLog file under git; instead, use
'C-c C-a' to insert its contents into your *vc-log* buffer.
Or if 'log-edit-hook' includes 'log-edit-insert-changelog' (which it
does by default), they will be filled in for you automatically.
- Alternatively, you can use the vc-dwim command to maintain commit
messages. When you create a source directory, run the shell command
'git-changelog-symlink-init' to create a symbolic link from
ChangeLog to .git/c/ChangeLog. Edit this ChangeLog via its symlink
with Emacs commands like 'C-x 4 a', and commit the change using the
shell command 'vc-dwim --commit'. Type 'vc-dwim --help' for more.
** Committing changes by others
If committing changes written by someone else, commit in their name,
not yours. You can use 'git commit --author="AUTHOR"' to specify a
change's author.
** Branches
Future development normally takes place on the master branch.
Sometimes specialized features are developed on other branches before
possibly being merged to the master. Release branches are named
"emacs-NN" where NN is the major version number, and are mainly
intended for more-conservative changes such as bug fixes. Typically,
collective development is active on the master branch and possibly on
the current release branch. Periodically, the current release branch
is merged into the master, using the gitmerge function described in
admin/notes/git-workflow.
If you are fixing a bug that exists in the current release, be sure to
commit it to the release branch; it will be merged to the master
branch later by the gitmerge function.
Documentation fixes (in doc strings, in manuals, and in comments)
should always go to the release branch, if the documentation to be
fixed exists and is relevant to the release-branch codebase. Doc
fixes are always considered "safe" -- even when a release branch is in
feature freeze, it can still receive doc fixes.
When you know that the change will be difficult to merge to the
master (e.g., because the code on master has changed a lot), you can
apply the change to both master and branch yourself. It could also
happen that a change is cherry-picked from master to the release
branch, and so doesn't need to be merged back. In these cases,
say in the release branch commit message that there is no need to merge
the commit to master, by starting the commit message with "Backport:".
The gitmerge function excludes these commits from the merge to the master.
Some changes should not be merged to master at all, for whatever
reasons. These should be marked by including something like "Do not
merge to master" or anything that matches gitmerge-skip-regexp (see
admin/gitmerge.el) in the commit message.
** GNU ELPA
This repository does not contain the Emacs Lisp package archive
(elpa.gnu.org). See admin/notes/elpa for how to access the GNU ELPA
repository.
** Understanding Emacs internals
The best way to understand Emacs internals is to read the code. Some
source files, such as xdisp.c, have extensive comments describing the
design and implementation. The following resources may also help:
https://www.gnu.org/software/emacs/manual/html_node/elisp/Tips.html
https://www.gnu.org/software/emacs/manual/html_node/elisp/GNU-Emacs-Internals.html
or run 'info "(elisp)Tips"' or 'info "(elisp)GNU Emacs Internals"'.
The file etc/DEBUG describes how to debug Emacs bugs.
*** Non-ASCII characters in Emacs files
If you introduce non-ASCII characters into Emacs source files, use the
UTF-8 encoding unless it cannot do the job for some good reason.
Although it is generally a good idea to add 'coding:' cookies to
non-ASCII source files, cookies are not needed in UTF-8-encoded *.el
files intended for use only with Emacs version 24.5 and later.
*** Useful files in the admin/ directory
See all the files in admin/notes/* . In particular, see
admin/notes/newfile, see admin/notes/repo.
The file admin/MAINTAINERS records the areas of interest of frequent
Emacs contributors. If you are making changes in one of the files
mentioned there, it is a good idea to consult the person who expressed
an interest in that file, and/or get his/her feedback for the changes.
If you are a frequent contributor and have interest in maintaining
specific files, please record those interests in that file, so that
others could be aware of that.
*** git vs rename
Git does not explicitly represent a file renaming; it uses a percent
changed heuristic to deduce that a file was renamed. So if you are
planning to make extensive changes to a file after renaming it (or
moving it to another directory), you should:
- Create a feature branch.
- Commit the rename without any changes.
- Make other changes.
- Merge the feature branch to the master branch, instead of squashing
the commits into one. The commit message on this merge should
summarize the renames and all the changes.
This file is part of GNU Emacs.
GNU Emacs is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
GNU Emacs is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>.
Local variables:
mode: outline
paragraph-separate: "[ ]*$"
coding: utf-8
end: