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.
(Referring to a bug report is not as good as including it, because then we will have to look it up, and we have probably already deleted it if we've already fixed the bug.)
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.
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.
diff -c' 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. Unidiff format is better than contextless diffs, but not as easy to read as `
If you have GNU diff, use `
diff -c -F'^[_a-zA-Z0-9$]+ *('' when
making diffs of C code. This shows the name of the function that each
change occurs in.
The purpose of the change 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 read the `
ChangeLog' files in the `
src' and `
directories to see what sorts of information to put in, and to learn the
style that we use. If you would like your name to appear in the header
line, showing who made the change, send us the header line.
See Change Log.
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.