; Auto-commit of ChangeLog files.
[emacs.git] / CONTRIBUTE
blob7e697ddd89a51f9452a3279d75212092657956cb
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 - Any lines of the commit message that start with "; " are omitted
100   from the generated ChangeLog.
102 - Explaining the rationale for a design choice is best done in comments
103   in the source code.  However, sometimes it is useful to describe just
104   the rationale for a change; that can be done in the commit message
105   between the summary line and the file entries.
107 - Emacs generally follows the GNU coding standards when it comes to
108   ChangeLogs:
109   http://www.gnu.org/prep/standards/html_node/Change-Logs.html or
110   "(info (standards)Change Logs").  One exception is that we still
111   sometimes quote `like-this' (as the standards used to recommend)
112   rather than 'like-this' (as they do now), because `...' is so widely
113   used elsewhere in Emacs.
115 - Some of the rules in the GNU coding standards section 5.2
116   "Commenting Your Work" also apply to ChangeLog entries: they must be
117   in English, and be complete sentences starting with a capital and
118   ending with a period (except the summary line should not end in a
119   period).
121   They are preserved indefinitely, and have a reasonable chance of
122   being read in the future, so it's better that they have good
123   presentation.
125 - Use the present tense; describe "what the change does", not "what
126   the change did".
128 - Preferred form for several entries with the same content:
130         * lisp/help.el (view-lossage):
131         * lisp/kmacro.el (kmacro-edit-lossage):
132         * lisp/edmacro.el (edit-kbd-macro): Fix docstring, lossage is now 300.
134   (Rather than anything involving "ditto" and suchlike.)
136 - There is no standard or recommended way to identify revisions in
137   ChangeLog entries.  Using Git SHA1 values limits the usability of
138   the references to Git, and will become much less useful if Emacs
139   switches to a different VCS.  So we recommend against that.
141   One way to identify revisions is by quoting their summary line.
142   Another is with an action stamp - an RFC3339 date followed by !
143   followed by the committer's email - for example,
144   "2014-01-16T05:43:35Z!esr@thyrsus.com".  Often, "my previous commit"
145   will suffice.
147 - There is no need to mention files such as NEWS, MAINTAINERS, and
148   FOR-RELEASE, or to indicate regeneration of files such as
149   'configure', in the ChangeLog entry.  "There is no need" means you
150   don't have to, but you can if you want to.
152 ** Generating ChangeLog entries
154 - You can use various Emacs functions to ease the process of writing
155   ChangeLog entries; see (info "(emacs)Change Log Commands") or
156   http://www.gnu.org/software/emacs/manual/html_node/emacs/Change-Log-Commands.html.
158 - If you use Emacs VC, one way to format ChangeLog entries is to create
159   a top-level ChangeLog file manually, and update it with 'C-x 4 a' as
160   usual.  Do not register the ChangeLog file under git; instead, use
161   'C-c C-a' to insert its contents into into your *vc-log* buffer.
162   Or if 'log-edit-hook' includes 'log-edit-insert-changelog' (which it
163   does by default), they will be filled in for you automatically.
165 - Alternatively, you can use the vc-dwim command to maintain commit
166   messages.  When you create a source directory, run the shell command
167   'git-changelog-symlink-init' to create a symbolic link from
168   ChangeLog to .git/c/ChangeLog.  Edit this ChangeLog via its symlink
169   with Emacs commands like 'C-x 4 a', and commit the change using the
170   shell command 'vc-dwim --commit'.  Type 'vc-dwim --help' for more.
172 ** Branches
174 Development normally takes places on the trunk.
175 Sometimes specialized features are developed on separate branches
176 before possibly being merged to the trunk.
178 Development is discussed on the emacs-devel mailing list.
180 Sometime before the release of a new major version of Emacs a "feature
181 freeze" is imposed on the trunk, to prepare for creating a release
182 branch.  No new features may be added to the trunk after this point,
183 until the release branch is created.  Announcements about the freeze
184 (and other important events) are made on the emacs-devel mailing
185 list under the "emacs-announce" topic, and not anywhere else.
187 The trunk branch is named "master" in git; release branches are named
188 "emacs-nn" where "nn" is the major version.
190 If you are fixing a bug that exists in the current release, be sure to
191 commit it to the release branch; it will be merged to the master
192 branch later.
194 However, if you know that the change will be difficult to merge to the
195 trunk (eg because the trunk code has changed a lot), you can apply the
196 change to both trunk and branch yourself.  Indicate in the release
197 branch commit log that there is no need to merge the commit to the
198 trunk; start the commit message with "Backport:".  gitmerge.el will
199 then exclude that commit from the merge to trunk.
202 ** Other process information
204 See all the files in admin/notes/* .  In particular, see
205 admin/notes/newfile, see admin/notes/repo.
207 *** git vs rename
209 Git does not explicitly represent a file renaming; it uses a percent
210 changed heuristic to deduce that a file was renamed.  So if you are
211 planning to make extensive changes to a file after renaming it (or
212 moving it to another directory), you should:
214 - create a feature branch
216 - commit the rename without any changes
218 - make other changes
220 - merge the feature branch to trunk, _not_ squashing the commits into
221   one.  The commit message on this merge should summarize the renames
222   and all the changes.
224 ** Emacs Mailing lists.
226 Discussion about Emacs development takes place on emacs-devel@gnu.org.
228 Bug reports and fixes, feature requests and implementations should be
229 sent to bug-gnu-emacs@gnu.org, the bug/feature list.  This is coupled
230 to the tracker at http://debbugs.gnu.org .
232 You can subscribe to the mailing lists, or see the list archives,
233 by following links from http://savannah.gnu.org/mail/?group=emacs .
235 To email a patch you can use a shell command like 'git format-patch -1'
236 to create a file, and then attach the file to your email.  This nicely
237 packages the patch's commit message and changes.
239 ** Document your changes.
241 Any change that matters to end-users should have an entry in etc/NEWS.
243 Doc-strings should be updated together with the code.
245 Think about whether your change requires updating the manuals.  If you
246 know it does not, mark the NEWS entry with "---".  If you know
247 that *all* the necessary documentation updates have been made, mark
248 the entry with "+++".  Otherwise do not mark it.
250 Please see (info "(elisp)Documentation Tips") or
251 https://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tips.html
252 for more specific tips on Emacs's doc style.  Use 'checkdoc' to check
253 for documentation errors before submitting a patch.
255 ** Test your changes.
257 Please test your changes before committing them or sending them to the
258 list.
260 Emacs uses ERT, Emacs Lisp Regression Testing, for testing.  See (info
261 "(ert)") or https://www.gnu.org/software/emacs/manual/html_node/ert/
262 for more information on writing and running tests.
264 To run tests on the entire Emacs tree, run "make check" from the
265 top-level directory.  Most tests are in the directory
266 "test/automated".  From the "test/automated" directory, run "make
267 <filename>" to run the tests for <filename>.el(c).  See
268 "test/automated/Makefile" for more information.
270 ** Understanding Emacs Internals.
272 The best way to understand Emacs Internals is to read the code,
273 but the nodes "Tips" and "GNU Emacs Internals" in the Appendix
274 of the Emacs Lisp Reference Manual may also help.  Some source files,
275 such as xdisp.c, have large commentaries describing the design and
276 implementation in more detail.
278 The file etc/DEBUG describes how to debug Emacs bugs.
282 This file is part of GNU Emacs.
284 GNU Emacs is free software: you can redistribute it and/or modify
285 it under the terms of the GNU General Public License as published by
286 the Free Software Foundation, either version 3 of the License, or
287 (at your option) any later version.
289 GNU Emacs is distributed in the hope that it will be useful,
290 but WITHOUT ANY WARRANTY; without even the implied warranty of
291 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
292 GNU General Public License for more details.
294 You should have received a copy of the GNU General Public License
295 along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
297 Local variables:
298 mode: outline
299 paragraph-separate: "[  \f]*$"
300 end: