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