52.5 Sending Patches for GNU Emacs

If you would like to write bug fixes or improvements for GNU Emacs, that is very helpful. When you send your changes, please follow these guidelines to make it easy for the maintainers to use them. If you don’t follow these guidelines, your information might still be useful, but using it will take extra work. Maintaining GNU Emacs is a lot of work in the best of circumstances, and we can’t keep up unless you do your best to help.

Every patch must have several pieces of information before we can properly evaluate it.

When you have all these pieces, bundle them up in a mail message and send it to the developers. Sending it to [email protected] (which is the bug/feature list) is recommended, because that list is coupled to a tracking system that makes it easier to locate patches. If your patch is not complete and you think it needs more discussion, you might want to send it to [email protected] instead. If you revise your patch, send it as a followup to the initial topic.

We prefer to get the patches as plain text, either inline (be careful your mail client does not change line breaks) or as MIME attachments.

• Include an explanation with your changes of what problem they fix or what improvement they bring about.

  • For a fix for an existing bug, it is best to reply to the relevant discussion on the ‘ bug-gnu-emacs’ list, or the bug entry in the GNU Bug Tracker at https://debbugs.gnu.org. Explain why your change fixes the bug.

  • For a new feature, include a description of the feature and your implementation.

  • For a new bug, include a proper bug report for the problem you think you have fixed. We need to convince ourselves that the change is right before installing it. Even if it is correct, we might have trouble understanding it if we don’t have a way to reproduce the problem.

• Include all the comments that are appropriate to help people reading the source in the future understand why this change was needed.

• Don’t mix together changes made for different reasons. Send them individually.

If you make two changes for separate reasons, then we might not want to install them both. We might want to install just one. If you send them all jumbled together in a single set of diffs, we have to do extra work to disentangle them—to figure out which parts of the change serve which purpose. If we don’t have time for this, we might have to ignore your changes entirely.

If you send each change as soon as you have written it, with its own explanation, then two changes never get tangled up, and we can consider each one properly without any extra work to disentangle them.

• Send each change as soon as that change is finished. Sometimes people think they are helping us by accumulating many changes to send them all together. As explained above, this is absolutely the worst thing you could do.

Since you should send each change separately, you might as well send it right away. That gives us the option of installing it immediately if it is important.

• The patch itself.

Use ‘ diff -u’ to make your diffs. Diffs without context are hard to install reliably. More than that, they are hard to study; we must always study a patch to decide whether we want to install it. Context format is better than contextless diffs, but we prefer the unified format.

If you have GNU diff, use ‘ diff -u -F'^[_a-zA-Z0-9$]\+ *('’ when making diffs of C code. This shows the name of the function that each change occurs in.

If you are using the Emacs repository, make sure your copy is up-to-date (e.g., with git pull). You can commit your changes to a private branch and generate a patch from the master version by using git format-patch master. Or you can leave your changes uncommitted and use git diff.

• Avoid any ambiguity as to which is the old version and which is the new. Please make the old version the first argument to diff, and the new version the second argument. And please give one version or the other a name that indicates whether it is the old version or your new changed one.

• Write the commit log entries for your changes. This is both to save us the extra work of writing them, and to help explain your changes so we can understand them.

The purpose of the commit log is to show people where to find what was changed. So you need to be specific about what functions you changed; in large functions, it’s often helpful to indicate where within the function the change was.

On the other hand, once you have shown people where to find the change, you need not explain its purpose in the change log. Thus, if you add a new function, all you need to say about it is that it is new. If you feel that the purpose needs explaining, it probably does—but put the explanation in comments in the code. It will be more useful there.

Please look at the commit log entries of recent commits to see what sorts of information to put in, and to learn the style that we use. Note that, unlike some other projects, we do require commit logs for documentation, i.e., Texinfo files. See Change Logs, see https://www.gnu.org/prep/standards/html_node/Change-Log-Concepts.html, See Change Log Concepts in GNU Coding Standards.

• When you write the fix, keep in mind that we can’t install a change that would break other systems. Please think about what effect your change will have if compiled on another type of system.

Sometimes people send fixes that might be an improvement in general—but it is hard to be sure of this. It’s hard to install such changes because we have to study them very carefully. Of course, a good explanation of the reasoning by which you concluded the change was correct can help convince us.

The safest changes are changes to the configuration files for a particular machine. These are safe because they can’t create new bugs on other machines.

Please help us keep up with the workload by designing the patch in a form that is clearly safe to install.