Contributing to Emacs

If you found a bug and fixed it, you should send your patch as a bug report. Same as reporting a bug, use M-x report-emacs-bug, and append [PATCH] in front of the title, e.g., [PATCH] Something doesn’t work. And add your patch to your email. (See 4.4.)

Go to Emacs-devel Info Page, and fill in the form to subscribe. Make sure you select “No” for “Would you like to receive list mail batched in a daily digest?”. If you select “Yes”, instead of receiving messages, you receive a “daily digest” every day, which is less useful because 1) you don’t see the full conversation, 2) you can’t participate in the discussion.

Emacs-devel is busy, there are a few dozen messages every day. if you don’t want your inbox flooded, you better set up a separate mail folder for them. As an example, this is what I do on Gmail: I go to “Settings”, “Filters and Blocked Addresses”, “Create a new filter”, filter any mail that has the words “[email protected]”, and asks Gmail to skip the inbox and apply “emacs-devel” label. The effect is that all emacs-devel messages don’t appear in your inbox and instead show up in the emacs-devel folder.

In general, give it a week or so before pinging your message. Normally when no one replies to a new message, it is because people who have seen it don’t know enough to say anything intelligent about the topic.

Even with a patch, or you are not sure if it should be considered a bug (given you can reproduce it with vanilla Emacs), report it as a bug. See 1.1 for detail.

You don’t need a copyright assignment to send patches for review. But for the patch to merge into Emacs, it needs to have a copyright assignment signed if it is non-trivial (≥ 15 lines of code, as a rule of thumb). By signing the assignment, you share the copyright of your code with FSF ¹. (See more at Why Copyright Assignment and Misconceptions About the Assignment.)

You need to first check with your employer before signing it. Most of the time it’s no problem. To sign the assignment, ask for a form on the mailing list, and someone will send it to you. You fill it in and send it to an “FSF clerk”, then he sends you the document to sign, either by email or by mail. You sign it and send it back, and he sends you the final document with an FSF signature on it.

• Write regular sentences in comments, i.e., with capitalization and period. Fill comments with M-q (fill-paragraph).
• Comments should be in American English and with two spaces after every sentence.
• Don’t write over 80–90 columns (I don’t know if there is a hard limit, but in general try to keep in with the rest of the code).

The general format:

Summary line (no ending period)

Some more info (optional).

​* file1: Change.
​* file2 (variable1): Change.
​* file3 (function1, function2, variable3): Same change.
​* file4 (variable4): Change 1.
(function5): Change 2.
(function6, macro7): Same change.

• The file path is relative to the source root, e.g., /lisp/progmodes/gdb-mi.el.
• In Change, document what changed, not why the change is made. “Why” is better put in the comments.
• For new function​/​variable​/​macro, It suffices to say “New function​/​variable​/​macro”.
• Don’t exceed 78 characters each line.
• Try to use only ASCII characters (so people on limited terminals can view these messages). For example, prefer straight quotes over curly quotes.
• Quote function​/​variable​/​macro like 'this'​, not like `this'.
• Sames as comments—American English and two spaces after every sentence.
• Use the present tense.
• (tip) M-x fill-paragraph is your friend.

Create a single patch for each change. Don’t send a patch with three new features combined, that is harder to review; on the other hand, don’t send a series of patches for a single feature, squash² them into one patch. Also, send your patch early and small and update along the way, that also helps other people to review it. To save you from googling, here are some ways to create a patch:

1. Use Magit. To generate a quick diff patch, open a diff buffer by either d d on a change or commit; in the diff buffer, hit W s. To generate a patch from a commit, go on to a commit and d c, then go to the diff buffer and W s.
2. You can also use vc-diff and save that buffer to a file.
3. From command line, git format-patch -1 --stdout > file where 1 is the number of commits you want to include.

To send your patch, write an email to the mailing list: emacs-devel. Drag your patch to the end of the message after the signature. Normally this is all it needs. Sometimes the message could be garbled; in that case, changing the message to plain text usually helps. You can also send a patch to debbugs—the bug tracker—if the patch is a bug fix. (See 6.)