CONTRIBUTE 11.1 KB
Newer Older
1
This file contains information on Emacs developer processes.
Juri Linkov's avatar
Juri Linkov committed
2

3 4 5
For information on contributing to Emacs as a non-developer, see
(info "(emacs)Contributing") or
http://www.gnu.org/software/emacs/manual/html_node/emacs/Contributing.html
Juri Linkov's avatar
Juri Linkov committed
6

7
* Information for Emacs Developers.
Juri Linkov's avatar
Juri Linkov committed
8

9
An "Emacs Developer" is someone who contributes a lot of code or
10
documentation to the Emacs repository. Generally, they have write
11 12
access to the Emacs git repository on Savannah
https://savannah.gnu.org/git/?group=emacs.
Juri Linkov's avatar
Juri Linkov committed
13

14
** Write access to the Emacs repository.
Juri Linkov's avatar
Juri Linkov committed
15

16 17 18
Once you become a frequent contributor to Emacs, we can consider
giving you write access to the version-control repository. Request
access on the emacs-devel@gnu.org mailing list.
Juri Linkov's avatar
Juri Linkov committed
19

20
** Using the Emacs repository
Juri Linkov's avatar
Juri Linkov committed
21

22
Emacs uses git for the source code repository.
Juri Linkov's avatar
Juri Linkov committed
23

24 25 26
See http://www.emacswiki.org/emacs/GitQuickStartForEmacsDevs to get
started, and http://www.emacswiki.org/emacs/GitForEmacsDevs for more
advanced information.
Juri Linkov's avatar
Juri Linkov committed
27

28
Alternately, see admin/notes/git-workflow.
Juri Linkov's avatar
Juri Linkov committed
29

30 31
If committing changes written by someone else, make the commit in
their name, not yours.  git distinguishes between the author
32 33
and the committer; use the --author option on the commit command to
specify the actual author; the committer defaults to you.
Juri Linkov's avatar
Juri Linkov committed
34

35
** Commit messages
36

Dmitry Gutov's avatar
Dmitry Gutov committed
37 38 39 40
When a release is prepared, the commit messages are used to generate
the ChangeLog file.  So a typical patch does not touch any of the
ChangeLog files in the repository, but contains the ChangeLog entries
in its message.  Here is an example commit message (indented):
41 42 43 44

	Deactivate shifted region

	Do not silently extend a region that is not highlighted;
45
	this can happen after a shift (Bug#19003).
46 47 48 49 50 51
	* 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.

The general format is as follows.
52

53 54
- Start with a single unindented summary line explaining the change,
  then an empty line, then unindented ChangeLog entries.
55

56
- Limit lines in commit messages to 78 characters, unless they consist
57 58 59 60 61
  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.
62 63 64 65 66 67 68 69 70 71

- 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.

- 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.

72 73
- Commit messages should contain only printable UTF-8 characters.

Paul Eggert's avatar
Paul Eggert committed
74
- Commit messages should not contain the "Signed-off-by:" lines that
75 76
  are used in some other projects.

77 78 79 80 81 82 83
- Emacs generally follows the GNU coding standards when it comes to
  ChangeLogs:
  http://www.gnu.org/prep/standards/html_node/Change-Logs.html .  One
  exception is that we still sometimes quote `like-this' (as the
  standards used to recommend) rather than 'like-this' (as they do
  now), because `...' is so widely used elsewhere in Emacs.

84
- Some of the rules in the GNU coding standards section 5.2
85
  "Commenting Your Work" also apply to ChangeLog entries: they must be
86 87 88 89
  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).

90 91 92
  They are preserved indefinitely, and have a reasonable chance of
  being read in the future, so it's better that they have good
  presentation.
93 94 95 96

- Use the present tense; describe "what the change does", not "what
  the change did".

97 98
- Preferred form for several entries with the same content:

99 100 101
	* lisp/help.el (view-lossage):
	* lisp/kmacro.el (kmacro-edit-lossage):
	* lisp/edmacro.el (edit-kbd-macro): Fix docstring, lossage is now 300.
102 103 104

  (Rather than anything involving "ditto" and suchlike.)

105 106 107 108 109 110 111
- If the commit has authors other than yourself, the commit message
  should contain a separate line like the following:

	Co-authored-by: Joe Schmoe <j.schmoe@example.org>

- If the commit is a tiny change that is exempt from copyright paperwork,
  the commit message should contain a separate line like the following:
112

113 114
	Copyright-paperwork-exempt: yes

115 116 117
- 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)".
118 119

- In ChangeLog entries, there is no standard or recommended way to
120 121 122 123 124 125 126 127
  identify revisions.

  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:35Z!esr@thyrsus.com". Often, "my previous commit"
  will suffice.

Dmitry Gutov's avatar
Dmitry Gutov committed
128 129 130 131
- There is no need to mention files such as NEWS, MAINTAINERS, and
  FOR-RELEASE, or to indicate regeneration of files such as
  'configure', in the ChangeLog entry.  "There is no need" means you
  don't have to, but you can if you want to.
132

133
- If a commit message's first line starts with "; ", the message is
Dmitry Gutov's avatar
Dmitry Gutov committed
134
  ignored when generating ChangeLog history files via 'make ChangeLog'
135
  or via 'make change-history'.  You can use "; " for minor commits
Dmitry Gutov's avatar
Dmitry Gutov committed
136 137
  that do not need separate ChangeLog entries, as well as commits that
  only modify files that don't need these entries at all.
138 139 140 141 142 143 144 145

** Generating ChangeLog entries

- You can use various Emacs functions to ease the process of writing
  ChangeLog entries; see (info "(emacs)Change Log Commands") or
  http://www.gnu.org/software/emacs/manual/html_node/emacs/Change-Log-Commands.html.

- If you use Emacs VC, one way to format ChangeLog entries is to create
146
  a top-level ChangeLog file manually, and update it with 'C-x 4 a' as
147 148
  usual.  Do not register the ChangeLog file under git; instead, use
  'C-c C-a' to insert its contents into into your *vc-log* buffer.
149
  Or if 'log-edit-hook' includes 'log-edit-insert-changelog' (which it
150
  does by default), they will be filled in for you automatically.
151 152 153 154 155 156 157 158

- 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.

159 160 161 162 163 164 165 166 167 168 169
** branches

Development normally takes places on the trunk.
Sometimes specialized features are developed on separate branches
before possibly being merged to the trunk.

Development is discussed on the emacs-devel mailing list.

Sometime before the release of a new major version of Emacs a "feature
freeze" is imposed on the trunk, to prepare for creating a release
branch.  No new features may be added to the trunk after this point,
170 171 172
until the release branch is created. Announcements about the freeze
(and other important events) are made on the info-gnu-emacs mailing
list, and not anywhere else.
173

174 175
The trunk branch is named "master" in git; release branches are named
"emacs-nn" where "nn" is the major version.
176 177 178 179 180

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.

181 182 183 184 185 186
However, if you know that the change will be difficult to merge to the
trunk (eg because the trunk code has changed a lot), you can apply the
change to both trunk and branch yourself.  Indicate in the release
branch commit log that there is no need to merge the commit to the
trunk; start the commit message with "Backport:".  gitmerge.el will
then exclude that commit from the merge to trunk.
187 188 189


** Other process information
Juri Linkov's avatar
Juri Linkov committed
190

191 192
See all the files in admin/notes/* . In particular, see
admin/notes/newfile, see admin/notes/repo.
Juri Linkov's avatar
Juri Linkov committed
193

194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210
*** 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 trunk, _not_ squashing the commits into
  one. The commit message on this merge should summarize the renames
  and all the changes.

Juri Linkov's avatar
Juri Linkov committed
211 212 213 214
** Emacs Mailing lists.

Discussion about Emacs development takes place on emacs-devel@gnu.org.

215 216 217
Bug reports and fixes, feature requests and implementations should be
sent to bug-gnu-emacs@gnu.org, the bug/feature list.  This is coupled
to the tracker at http://debbugs.gnu.org .
Juri Linkov's avatar
Juri Linkov committed
218

219 220
You can subscribe to the mailing lists, or see the list archives,
by following links from http://savannah.gnu.org/mail/?group=emacs .
Juri Linkov's avatar
Juri Linkov committed
221

222 223 224 225
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.

Juri Linkov's avatar
Juri Linkov committed
226 227
** Document your changes.

228
Any change that matters to end-users should have an entry in etc/NEWS.
Juri Linkov's avatar
Juri Linkov committed
229

230 231 232 233 234 235
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, mark
the entry with "+++". Otherwise do not mark it.
Juri Linkov's avatar
Juri Linkov committed
236

237 238
Please see (info "(elisp)Documentation Tips") or
https://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tips.html
239
for more specific tips on Emacs's doc style.  Use 'checkdoc' to check
240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256
for documentation errors before submitting a patch.

** Test your changes.

Please test your changes before committing them or sending them to the
list.

Emacs uses ERT, Emacs Lisp Regression Testing, for testing.  See (info
"(ert)") or https://www.gnu.org/software/emacs/manual/html_node/ert/
for more information on writing and running tests.

To run tests on the entire Emacs tree, run "make check" from the
top-level directory.  Most tests are in the directory
"test/automated".  From the "test/automated" directory, run "make
<filename>" to run the tests for <filename>.el(c).  See
"test/automated/Makefile" for more information.

Juri Linkov's avatar
Juri Linkov committed
257 258 259 260 261 262 263 264 265 266 267 268
** Understanding Emacs Internals.

The best way to understand Emacs Internals is to read the code,
but the nodes "Tips" and "GNU Emacs Internals" in the Appendix
of the Emacs Lisp Reference Manual may also help.

The file etc/DEBUG describes how to debug Emacs bugs.



This file is part of GNU Emacs.

269
GNU Emacs is free software: you can redistribute it and/or modify
Juri Linkov's avatar
Juri Linkov committed
270
it under the terms of the GNU General Public License as published by
271 272
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
Juri Linkov's avatar
Juri Linkov committed
273 274 275 276 277 278 279

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
280
along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
Juri Linkov's avatar
Juri Linkov committed
281 282 283 284 285

Local variables:
mode: outline
paragraph-separate: "[ 	]*$"
end: