Home / Notes /

Contributing to Emacs

Table of Contents

Emacs, the editor we all use and love, has been running for decades, receiving contribution from hundreds of hackers along the way. Because it predates recent popular workflows (a.k.a GitHub and friends) by many years, you can’t do the usual thing—open issues, fork and make PR’s, etc. However, Emacs’s development workflow isn’t as tedious and difficult as many people imagine (in particular, you don’t need Gnus or deal with email in Emacs, or set up anything fancy).

In this post, I show what I’ve learned as an Emacs newcomer about participating in the development of Emacs. I hope that by sharing what does contributing to Emacs look like, more people know what to expect and feel comfortable to join the development of Emacs.

1 Report Emacs bug

I won’t go into details here, because I think most people nowadays are well educated by numerous communities on how to report a bug properly. In the case of Emacs, in addition, you want to reproduce the bug with vanilla Emacs, i.e., without your configurations. You can start one with emacs -Q. And in Emacs type M-x report-emacs-bug RET, then C-c M-i to use your mail application to send the bug report through email (Emacs instructs you of all this). Then just wait for a developer to reply to your email (see? No setup needed). The only thing to remember is to make sure you use “reply all” when replying to emails (more on that in 2.)

1.1 Report bugs with patch

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

2 The mailing list

The mailing list is the main channel for general discussion on Emacs development. A mailing list has subscribers. When someone sends a mail to (or cc) the mailing list address, the mailing list server forwards that message to every subscriber, so everybody sees your mail. To start a new thread, send a mail to the mailing list server; to reply to someone’s message, simply “reply all”. Make sure you use “reply all” when replying to messages. If the message isn’t CC’ed to the mailing list server ([email protected]), other people on the list can’t see it.

2.1 Subscribe to Emacs-devel mailing list

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.

2.2 Tips

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.

2.3 No one replies?

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.

2.4 Don’t send bugs to emacs-devel

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.

3 Get Emacs’ source

The home page tells you how to clone Emacs’ source:

          git clone -b master git://git.sv.gnu.org/emacs.git

Once you have the source, you can find most of the information mentioned in this post in /CONTRIBUTE. For example, the first section demonstrates how to compile Emacs:

# More info is in INSTALL.
./autogen.sh
# You can use ./configure.sh --help to see the available options.
# This is the step where you enable/disable optional functionalities
# like dynamic modules, portable dumper, SVG, etc.
./configure.sh
make

And the executable is /src/emacs, welcome to the future (release)!

4 I have some code, what now?

4.2 Conventions in code

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

4.3 Conventions in commit messages

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.

4.4 Create a patch and send it

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, squash2 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.)

5 NEWS and manual

If you made a user-visible change, you should document this change in the NEWS file, possibly also update the manual. You don’t need to worry about these until your patch is finalized, though. So maybe skip this section for now. And Emacs maintainers will let you know what to do. Below is the relevant section in /CONTRIBUTE:

Any change that matters to end-users should have an entry in etc/NEWS. Try to start each NEWS entry with a sentence that summarizes the entry and takes just one line – this will allow to read NEWS in Outline mode after hiding the body of each entry.

Doc-strings should be updated together with the code.

New defcustom's should always have a ':version' tag stating the first Emacs version in which they will appear. Likewise with defcustom's whose value is changed – update their ':version' tag.

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 as part of your changes or those by others, mark the entry with "+++". Otherwise do not mark it.

If your change requires updating the manuals to document new functions/commands/variables/faces, then use the proper Texinfo command to index them; for instance, use @vindex for variables and @findex for functions/commands. For the full list of predefined indices, see Predefined Indices 3 or run the shell command 'info "(texinfo)Predefined Indices"'.

6 Debbugs

Debbugs is the bug tracker for the GNU operating system. Here is Emacs’ debbugs home page. I’ve covered how to report a bug. After you sent the email reporting the bug, debbugs will send you a confirmation email with a bug number. Instead of replying to messages in the bug report, you can also comment by sending a message to [email protected]. When the bug is fixed, you can send a message to <bug-number>[email protected], e.g., [email protected]. That closes the bug.

If you want to view currently open bugs, you can either browse online, or view them in Emacs: install the package debbugs and M-x debbugs-gnu. You can click on bugs to view the conversation. You can even reply by S w on a message, and write your message in Emacs, and hit C-c C-c to send. Chose “mail client” and Emacs invokes your default mail application to send this mail. Hit C-c C-k to cancel the message.

7 GNU ELPA

Have a good package? Add it to GNU ELPA!

Pros:

  • Get reviews from people that know Emacs and Emacs Lisp best.
  • Instantly available from vanilla Emacs.
  • You can host your package on other places, such as GitHub.
  • You can push to your package without review, and don’t need to follow Emacs conventions for commit messages.

Cons:

  • You need to sign the copyright assignment. And make sure all the contributors of your package (with a significant contribution, i.e., ≥ ~15 lines) signs it.

View README for more detailed info.

Footnotes:

1

In effect, the code is split into two versions, FSF distributes it’s version under GPL, and you can distribute yours version with whatever license you please.

2

Squash means combining several commits into one. It is easy to do with Magit: l l go to the log buffer; then go to the earliest commit you want to change, hit r i; hit s on the commits you want to squash, commits marked with “s” will squash up. You can also use M-n/p to move the order of commits; then hit C-c C-c to edit the new commit message, and C-c C-c again to confirm.

3

It was https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Predefined-Indices.html, I shortened it for the layout.

Written by Yuan Fu

First Published in 2020-05-02 Sat 14:44

Last modified in 2021-02-03 Wed 10:36

Send your comment to [email protected]