-
Notifications
You must be signed in to change notification settings - Fork 7
/
Copy pathcontribute_emacs.haml
185 lines (140 loc) · 7.37 KB
/
contribute_emacs.haml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
%h1 Contributing to Emacs
Please consider contributing patches to Emacs, even if you're an Emacs novice.
*Especially* if you're an Emacs novice--no-one is better qualified to judge the
introductory documentation. Contribute *now*, before Stockholm syndrome sets
in!
%h2 Reporting a bug
`M-x report-emacs-bug` will open a mail buffer with a template ready for you to
fill with information. You probably haven't configured Emacs to be able to send
email, but you can copy from this buffer and paste into your favorite email
client.
Do follow the instructions in that buffer. In particular, make sure you can
reproduce the bug having run Emacs with `emacs -Q` (to confirm that it is a bug
in Emacs itself and not in your customizations or in a third-party package).
%h2 A simple documentation change
The documentation for `ido-find-file` says:
.titlebar<
\\*Help*
.window<
:preserve
C-j Select the current prompt as the buffer or file.
If no buffer or file is found, prompt for a new one.
.modeline<
:preserve
-U:%%- <b>*Help*</b> 32% L22 (Help View)-----------------------------------------------
.echoarea<
After reading that I still didn't know what `C-j` (at the `ido-find-file`
prompt) actually does. It turns out to mean "use whatever you've typed
verbatim" instead of using `ido`'s fuzzy matching. I'll submit a patch to the
documentation string.
%h2 Making a patch, the 1980s way
.do
`M-x find-function ido-find-file`.
.do
Save a copy of this buffer (with `C-x C-w`) to `~/.emacs.d/ido.el` and
another copy to `~/.emacs.d/ido.el.orig`.
.do
Modify `~/.emacs.d/ido.el`. To test the change, evaluate (`C-M-x`) the
`defun` form you changed.
.do
Generate a patch with `diff -cp ido.el.orig ido.el`.[[1]]
.titlebar<
ido.el.patch
.window<
:preserve
<span class="diff-header">*** </span><span class="diff-header"><span class="diff-file-header">ido.el.orig</span></span><span class="diff-header"> 2012-04-07 10:20:31.000000000 +0100
--- </span><span class="diff-header"><span class="diff-file-header">ido.el</span></span><span class="diff-header"> 2012-04-07 10:28:59.000000000 +0100
</span><span class="diff-hunk-header">***************</span><span class="diff-function"> (defun ido-switch-buffer ()</span>
<span class="diff-hunk-header">*** 4041,4048 ****</span>
<span class="diff-context"> RET Select the buffer at the front of the list of matches. If the
list is empty, possibly prompt to create new buffer.
</span><span class="diff-indicator-changed">!</span><span class="diff-changed"> \\[ido-select-text] Select the current prompt as the buffer.
</span><span class="diff-indicator-changed">!</span><span class="diff-changed"> If no buffer is found, prompt for a new one.
</span><span class="diff-context">
\\[ido-next-match] Put the first element at the end of the list.
\\[ido-prev-match] Put the last element at the start of the list.
</span><span class="diff-hunk-header">--- 4041,4047 ----</span>
<span class="diff-context"> RET Select the buffer at the front of the list of matches. If the
list is empty, possibly prompt to create new buffer.
</span><span class="diff-indicator-changed">!</span><span class="diff-changed"> \\[ido-select-text] Use the current input string verbatim.
</span><span class="diff-context">
\\[ido-next-match] Put the first element at the end of the list.
\\[ido-prev-match] Put the last element at the start of the list.
</span><span class="diff-hunk-header">***************</span><span class="diff-function"> (defun ido-find-file ()</span>
<span class="diff-hunk-header">*** 4128,4135 ****</span>
<span class="diff-context"> RET Select the file at the front of the list of matches. If the
list is empty, possibly prompt to create new file.
</span><span class="diff-indicator-changed">!</span><span class="diff-changed"> \\[ido-select-text] Select the current prompt as the buffer or file.
</span><span class="diff-indicator-changed">!</span><span class="diff-changed"> If no buffer or file is found, prompt for a new one.
</span><span class="diff-context">
\\[ido-next-match] Put the first element at the end of the list.
\\[ido-prev-match] Put the last element at the start of the list.
</span><span class="diff-hunk-header">--- 4127,4133 ----</span>
<span class="diff-context"> RET Select the file at the front of the list of matches. If the
list is empty, possibly prompt to create new file.
</span><span class="diff-indicator-changed">!</span><span class="diff-changed"> \\[ido-select-text] Use the current input string verbatim.
</span><span class="diff-context">
\\[ido-next-match] Put the first element at the end of the list.
\\[ido-prev-match] Put the last element at the start of the list.
</span>
.modeline<
:preserve
-U:--- <b>ido.el.patch</b> Top L1 (Diff)-----------------------------------------------
.echoarea<
%h2 Making a patch in the 21st century[[2]]
Ideally you'd make the patch against the latest (unreleased) version of the
Emacs source code, instead of version 24.1. Someone else might even have fixed
your problem already! The Emacs source code is hosted at [savannah.gnu.org](
http://savannah.gnu.org/projects/emacs) and you can grab the source code from
the official Bazaar repository:
.do
`bzr branch bzr://bzr.savannah.gnu.org/emacs/trunk`
Or, if you prefer git, from the git mirror (which can [allegedly](
http://emacswiki.org/emacs/EmacsFromGit) be up to one day behind the Bazaar
repo):
.do
`git clone git://git.savannah.gnu.org/emacs.git`
Note that either one of the above commands will take quite a while, but you'll
only do it once. I'll use git in the following instructions.
.do
Create a private (local) branch for your changes:
`git checkout -b ido-el-documentation --track master`
.do
Make the change on the source files directly. Test.
.do
`git commit -am "* ido.el: Documentation for C-j in ido-find-file and ido-switch-buffer."`
.do
`git format-patch master`
In future, before starting on another change you'll want to pull the latest
changes from upstream:
.do
`git checkout master`
`git pull --rebase`[[3]]
%h2 Send the patch
Send the patch to the same email address as `M-x report-emacs-bug`. But first
read the [instructions for contributing to Emacs](
http://git.savannah.gnu.org/cgit/emacs.git/plain/etc/CONTRIBUTE) and the [Emacs
Lisp tips and conventions](
http://www.gnu.org/software/emacs/manual/html_node/elisp/Tips.html).
%h2 Contributing to third-party packages
Try to find contribution guidelines on the package's website: Where to email
your patch, the preferred formatting of the patch and its changelog message,
etc.
If the package is hosted on github, the package maintainers may be open to pull
requests via github's interface.
#footnotes
[[1]]:
Don't ask me why the Emacs maintainers don't like unified diffs (`diff -u`).
They [specifically ask](
http://git.savannah.gnu.org/cgit/emacs.git/tree/etc/CONTRIBUTE?id=9771cd41#n103)
for `diff -c`.
[[2]]:
The 21st century requires half a gig of disk space and a 30-minute download.
[[3]]:
The `--rebase` is to avoid complicated merges in the history if you have
local un-pushed commits on the master branch. Though if you've followed these
instructions, your local changes should only ever be on private branches, not
on master.