Merge from gnulib
[emacs.git] / CONTRIBUTE
blobbf23155426164cc607a99287a95a35a91369d2d1
1 This file contains information on Emacs developer processes.
3 For information on contributing to Emacs as a non-developer, see
4 (info "(emacs)Contributing") or
5 http://www.gnu.org/software/emacs/manual/html_node/emacs/Contributing.html
7 * Information for Emacs Developers.
9 An "Emacs Developer" is someone who contributes a lot of code or
10 documentation to the Emacs repository.  Generally, they have write
11 access to the Emacs git repository on Savannah
12 https://savannah.gnu.org/git/?group=emacs.
14 ** Write access to the Emacs repository.
16 Once you become a frequent contributor to Emacs, we can consider
17 giving you write access to the version-control repository.  Request
18 access on the emacs-devel@gnu.org mailing list.  Also, be sure to
19 subscribe to the emacs-devel@gnu.org mailing list and include the
20 "emacs-announce" topic, so that you get the announcements about
21 feature freeze and other important events.
23 ** Using the Emacs repository
25 Emacs uses Git for the source code repository.
27 See http://www.emacswiki.org/emacs/GitQuickStartForEmacsDevs to get
28 started, and http://www.emacswiki.org/emacs/GitForEmacsDevs for more
29 advanced information.
31 Alternately, see admin/notes/git-workflow.
33 If committing changes written by someone else, make the commit in
34 their name, not yours.  Git distinguishes between the author
35 and the committer; use the --author option on the commit command to
36 specify the actual author; the committer defaults to you.
38 ** Commit messages
40 Emacs development no longer stores descriptions of new changes in
41 ChangeLog files.  Instead, a single ChangeLog file is generated from
42 the commit messages when a release is prepared.  So changes you commit
43 should not touch any of the ChangeLog files in the repository, but
44 instead should contain the log entries in the commit message.  Here is
45 an example of a commit message (indented):
47         Deactivate shifted region
49         Do not silently extend a region that is not highlighted;
50         this can happen after a shift (Bug#19003).
51         * doc/emacs/mark.texi (Shift Selection): Document the change.
52         * lisp/window.el (handle-select-window):
53         * src/frame.c (Fhandle_switch_frame, Fselected_frame):
54         Deactivate the mark.
56 Below are some rules and recommendations for formatting commit
57 messages:
59 - Start with a single unindented summary line explaining the change;
60   do not end this line with a period.  If that line starts with a
61   semi-colon and a space "; ", the log message will be ignored when
62   generating the ChangeLog file.  Use this for minor commits that do
63   not need separate ChangeLog entries, such as changes in etc/NEWS.
65 - After the summary line, there should be an empty line, then
66   unindented ChangeLog entries.
68 - Limit lines in commit messages to 78 characters, unless they consist
69   of a single word of at most 140 characters; this is enforced by a
70   commit hook.  It's nicer to limit the summary line to 50 characters;
71   this isn't enforced.  If the change can't be summarized so briefly,
72   add a paragraph after the empty line and before the individual file
73   descriptions.
75 - If only a single file is changed, the summary line can be the normal
76   file first line (starting with the asterisk).  Then there is no
77   individual files section.
79 - If the commit has more than one author, the commit message should
80   contain separate lines to mention the other authors, like the
81   following:
83         Co-authored-by: Joe Schmoe <j.schmoe@example.org>
85 - If the commit is a tiny change that is exempt from copyright paperwork,
86   the commit message should contain a separate line like the following:
88         Copyright-paperwork-exempt: yes
90 - The commit message should contain "Bug#NNNNN" if it is related to
91   bug number NNNNN in the debbugs database.  This string is often
92   parenthesized, as in "(Bug#19003)".
94 - Commit messages should contain only printable UTF-8 characters.
96 - Commit messages should not contain the "Signed-off-by:" lines that
97   are used in some other projects.
99 - Explaining the rationale for a design choice is best done in comments
100   in the source code.  However, sometimes it is useful to describe just
101   the rationale for a change; that can be done in the commit message
102   between the summary line and the file entries.
104 - Emacs generally follows the GNU coding standards when it comes to
105   ChangeLogs:
106   http://www.gnu.org/prep/standards/html_node/Change-Logs.html or
107   "(info (standards)Change Logs").  One exception is that we still
108   sometimes quote `like-this' (as the standards used to recommend)
109   rather than 'like-this' (as they do now), because `...' is so widely
110   used elsewhere in Emacs.
112 - Some of the rules in the GNU coding standards section 5.2
113   "Commenting Your Work" also apply to ChangeLog entries: they must be
114   in English, and be complete sentences starting with a capital and
115   ending with a period (except the summary line should not end in a
116   period).
118   They are preserved indefinitely, and have a reasonable chance of
119   being read in the future, so it's better that they have good
120   presentation.
122 - Use the present tense; describe "what the change does", not "what
123   the change did".
125 - Preferred form for several entries with the same content:
127         * lisp/help.el (view-lossage):
128         * lisp/kmacro.el (kmacro-edit-lossage):
129         * lisp/edmacro.el (edit-kbd-macro): Fix docstring, lossage is now 300.
131   (Rather than anything involving "ditto" and suchlike.)
133 - There is no standard or recommended way to identify revisions in
134   ChangeLog entries.  Using Git SHA1 values limits the usability of
135   the references to Git, and will become much less useful if Emacs
136   switches to a different VCS.  So we recommend against that.
138   One way to identify revisions is by quoting their summary line.
139   Another is with an action stamp - an RFC3339 date followed by !
140   followed by the committer's email - for example,
141   "2014-01-16T05:43:35Z!esr@thyrsus.com".  Often, "my previous commit"
142   will suffice.
144 - There is no need to mention files such as NEWS, MAINTAINERS, and
145   FOR-RELEASE, or to indicate regeneration of files such as
146   'configure', in the ChangeLog entry.  "There is no need" means you
147   don't have to, but you can if you want to.
149 ** Generating ChangeLog entries
151 - You can use various Emacs functions to ease the process of writing
152   ChangeLog entries; see (info "(emacs)Change Log Commands") or
153   http://www.gnu.org/software/emacs/manual/html_node/emacs/Change-Log-Commands.html.
155 - If you use Emacs VC, one way to format ChangeLog entries is to create
156   a top-level ChangeLog file manually, and update it with 'C-x 4 a' as
157   usual.  Do not register the ChangeLog file under git; instead, use
158   'C-c C-a' to insert its contents into into your *vc-log* buffer.
159   Or if 'log-edit-hook' includes 'log-edit-insert-changelog' (which it
160   does by default), they will be filled in for you automatically.
162 - Alternatively, you can use the vc-dwim command to maintain commit
163   messages.  When you create a source directory, run the shell command
164   'git-changelog-symlink-init' to create a symbolic link from
165   ChangeLog to .git/c/ChangeLog.  Edit this ChangeLog via its symlink
166   with Emacs commands like 'C-x 4 a', and commit the change using the
167   shell command 'vc-dwim --commit'.  Type 'vc-dwim --help' for more.
169 ** Branches
171 Development normally takes places on the trunk.
172 Sometimes specialized features are developed on separate branches
173 before possibly being merged to the trunk.
175 Development is discussed on the emacs-devel mailing list.
177 Sometime before the release of a new major version of Emacs a "feature
178 freeze" is imposed on the trunk, to prepare for creating a release
179 branch.  No new features may be added to the trunk after this point,
180 until the release branch is created.  Announcements about the freeze
181 (and other important events) are made on the emacs-devel mailing
182 list under the "emacs-announce" topic, and not anywhere else.
184 The trunk branch is named "master" in git; release branches are named
185 "emacs-nn" where "nn" is the major version.
187 If you are fixing a bug that exists in the current release, be sure to
188 commit it to the release branch; it will be merged to the master
189 branch later.
191 However, if you know that the change will be difficult to merge to the
192 trunk (eg because the trunk code has changed a lot), you can apply the
193 change to both trunk and branch yourself.  Indicate in the release
194 branch commit log that there is no need to merge the commit to the
195 trunk; start the commit message with "Backport:".  gitmerge.el will
196 then exclude that commit from the merge to trunk.
199 ** Other process information
201 See all the files in admin/notes/* .  In particular, see
202 admin/notes/newfile, see admin/notes/repo.
204 *** git vs rename
206 Git does not explicitly represent a file renaming; it uses a percent
207 changed heuristic to deduce that a file was renamed.  So if you are
208 planning to make extensive changes to a file after renaming it (or
209 moving it to another directory), you should:
211 - create a feature branch
213 - commit the rename without any changes
215 - make other changes
217 - merge the feature branch to trunk, _not_ squashing the commits into
218   one.  The commit message on this merge should summarize the renames
219   and all the changes.
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 tracker at http://debbugs.gnu.org .
229 You can subscribe to the mailing lists, or see the list archives,
230 by following links from http://savannah.gnu.org/mail/?group=emacs .
232 To email a patch you can use a shell command like 'git format-patch -1'
233 to create a file, and then attach the file to your email.  This nicely
234 packages the patch's commit message and changes.
236 ** Document your changes.
238 Any change that matters to end-users should have an entry in etc/NEWS.
240 Doc-strings should be updated together with the code.
242 Think about whether your change requires updating the manuals.  If you
243 know it does not, mark the NEWS entry with "---".  If you know
244 that *all* the necessary documentation updates have been made, mark
245 the entry with "+++".  Otherwise do not mark it.
247 Please see (info "(elisp)Documentation Tips") or
248 https://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tips.html
249 for more specific tips on Emacs's doc style.  Use 'checkdoc' to check
250 for documentation errors before submitting a patch.
252 ** Test your changes.
254 Please test your changes before committing them or sending them to the
255 list.
257 Emacs uses ERT, Emacs Lisp Regression Testing, for testing.  See (info
258 "(ert)") or https://www.gnu.org/software/emacs/manual/html_node/ert/
259 for more information on writing and running tests.
261 To run tests on the entire Emacs tree, run "make check" from the
262 top-level directory.  Most tests are in the directory
263 "test/automated".  From the "test/automated" directory, run "make
264 <filename>" to run the tests for <filename>.el(c).  See
265 "test/automated/Makefile" for more information.
267 ** Understanding Emacs Internals.
269 The best way to understand Emacs Internals is to read the code,
270 but the nodes "Tips" and "GNU Emacs Internals" in the Appendix
271 of the Emacs Lisp Reference Manual may also help.  Some source files,
272 such as xdisp.c, have large commentaries describing the design and
273 implementation in more detail.
275 The file etc/DEBUG describes how to debug Emacs bugs.
279 This file is part of GNU Emacs.
281 GNU Emacs is free software: you can redistribute it and/or modify
282 it under the terms of the GNU General Public License as published by
283 the Free Software Foundation, either version 3 of the License, or
284 (at your option) any later version.
286 GNU Emacs is distributed in the hope that it will be useful,
287 but WITHOUT ANY WARRANTY; without even the implied warranty of
288 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
289 GNU General Public License for more details.
291 You should have received a copy of the GNU General Public License
292 along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
294 Local variables:
295 mode: outline
296 paragraph-separate: "[  \f]*$"
297 end: