Added text about patch formatting
[worg.git] / org-contribute.org
1 #+OPTIONS:    H:3 num:nil toc:t \n:nil @:t ::t |:t ^:t -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
2 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
3 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
4 #+TAGS:       Write(w) Update(u) Fix(f) Check(c) 
5 #+TITLE:      How to contribute to Org?
6 #+AUTHOR:     Worg people
7 #+EMAIL:      mdl AT imapmail DOT org
8 #+LANGUAGE:   en
9 #+PRIORITIES: A C B
10 #+CATEGORY:   worg
11
12 # This file is the default header for new Org files in Worg.  Feel free
13 # to tailor it to your needs.
14
15 [[file:index.org][{Back to Worg's index}]]
16
17 * Types of contributions
18
19 Every contribution to Org is very welcome.  Here is a list of areas where
20 your contribution will be useful:
21
22 - you can submit *bug reports* -- Before sending a bug report, make sure
23   you have read this section of Org's manual: [[http://orgmode.org/org.html#Feedback][Feedback]]  You can also read
24   this great text: "[[http://www.chiark.greenend.org.uk/~sgtatham/bugs.html][How to Send Bug Reports Effectively]]"
25
26 - you can submit *feature requests* -- Org is already mature, but new ideas
27   keep popping up.  If you want to request a feature, it might be a good
28   idea to have a look at the current [[http://orgmode.org/worg/org-issues.html][Issue tracking file]] which captures
29   both bug reports and feature requests.  Or dig into the mailing list for
30   possible previous discussions about your idea.  If you cannot find back
31   your idea, formulate it as detailed as possible, if possible with
32   examples, and send it to the mailing list.
33
34 - you can submit *patches* -- You can submit patches to the mailing list.
35   See the [[For Org contributors: preferred way of submitting patches][Preferred way of submitting patches]] section for details.
36
37   If your patch is against a file that is part of Emacs, then your
38   total contribution (all patches you submit) should change /less than
39   20 lines/.  If you contribute more, you have to assign the copyright
40   of your contribution to the Free Software Foundation (see below).
41   
42 - you can submit Org *add-ons* -- there are many Org add-ons.  The best way
43   is to submit your code to the mailing list to discuss it with people.  If
44   it is useful, you might consider contributing it to the =CONTRIB/=
45   directory in the git repository.
46
47 - you can submit material to the *Worg* website -- This website is made of
48   Org files that you can contribute to.  Learn what Worg is [[file:worg-about.org][about]] and how
49   to contribute to it [[file:worg-git.org][through git]].
50
51 * Copyright issues when contributing to Emacs org-mode
52
53 Org is made of many files.  Most of them are also distributed as part of
54 GNU Emacs.  These files are called the /Org core/, and they are all
55 copyrighted by the [[http://www.fsf.org][Free Software Foundation, Inc]].  If you consider
56 contributing to these files, your first need to grant the right to include
57 your works in GNU Emacs to the FSF.  For this you need to complete [[http://orgmode.org/request-assign-future.txt][this
58 form]], send it to [[mailto:assign@gnu.org][assign@gnu.org]], and tell the Org-mode maintainer when this
59 process is complete.  Some people consider this a hassle.  I don't want to
60 discuss this in detail here - there are some good reasons for getting the
61 copyright registered, an example is discussed in this [[http://twit.tv/floss117][FLOSS weekly podcast]].
62 Furthermore, by playing according to the Emacs rules, we gain the fantastic
63 advantage that every version of Emacs ships with Org-mode already fully
64 built in.  So please consider doing this - it makes our work as maintainers
65 so much easier, because we can then take your patches without any
66 additional work.
67
68 If you want to learn more about /why/ copyright assignments are
69 collected, read this: [[http://www.gnu.org/licenses/why-assign.html][Why the FSF gets copyright assignments from
70 contributors?]]
71
72 * For Org developers
73
74 1. Send your public key to [[mailto:emacs-orgmode%20AT%20dunsmor%20DOT%20com][Jason Dunsmore]].  
75
76 2. Wait for confirmation that your public key has been added to the server.
77
78 3. Clone =org-mode.git= repository like this:
79
80 : ~$ git clone orgmode@orgmode.org:org-mode.git
81
82 3. Commit your changes and push them.
83
84 If you are undertaking big changes, please create a dedicated branch for
85 them.
86
87 * For Org contributors: preferred way of submitting patches
88
89 Org-mode is developed using /git/ as the version control system.  Git
90 provides an amazing framework to collaborate on a project.  Git can be used
91 to make patches and send them via email -- this is perfectly fine for minor
92 changes.
93
94 As long as these patches are formatted properly, they will be
95 automatically registered at [[http://patchwork.newartisans.com/project/org-mode][John Wiegley's patchwork server]] and will
96 then be accepted, rejected, or sent back to the author with a request
97 for modification. In this context, "formatted properly" means that the
98 patches are included either plainly in the mail text, or as text
99 attachments (mime-type text, subtypes "x-patch", "x-diff", or
100 "plain"). In particular, binary types or, even worse,
101 "application/octet-stream" (the asinine default of some mail programs,
102 e.g. Thunderbird) are *not* going to be recognized. Please find out
103 how to convince your mail program to send proper attachments. Also, if
104 you include the patch inline, please make sure that your mail program
105 does not reformat it (although there are plenty of places further down
106 the line where that can happen, unfortunately). If you attach the
107 patch, then reformatting is not a problem.
108
109 ** Sending quick fixes
110
111 #+begin_quote
112   This command will make a patch between the staging area (in your
113   computer), and the file you modified:
114
115   : git diff -p org-whatever.el > org-whatever.el.diff
116
117   If you already committed your changes to your index (staging area), then
118   you should compare against a particular branch (in this example,
119   origin/master):
120
121   : git diff -p origin/master org-whatever.el > org-whatever.el.diff
122
123   You email the output to the mailing list, adding =[PATCH]= to the
124   subject, and description of what you fixed or changed.
125 #+end_quote
126
127 ** Sending commits
128
129 For more significant changes, you might want to work in several steps and
130 send each commit separately.  Here is the suggested workflow
131
132 #+begin_quote
133 :   ~$ git pull                 # make sure your repo is up to date
134 :   ~$ git branch my-changes    # create a new branch
135 :   ~$ git checkout my-changes  # switch to this new branch
136
137   ... make some changes (1) ...
138
139 :   ~$ git commit -m "This is change (1)"  # Commit your change
140
141   ... make another change (2) ...
142
143 :   ~$ git commit -m "This is change (2)"  # Commit your change
144 :   ~$ git format-patch master             # Creates two patches
145
146   ... Then two patches for your two commits are ready to be sent to the
147   list and detected by the patchwork server.
148 #+end_quote
149
150 Write useful commit messages: unless your change is very small, please
151 provide 1) a reason for it in your email and 2) a ChangeLog entry in the
152 commit message.
153
154 ** Sharing changes from a public branch
155
156 For more significant contributions, the best way to submit patches is
157 through public branches of your repository clone.
158
159 1. Clone our git repository at =http://orgmode.org/w/org-mode.git=
160
161 2. Create a repository that can be publicly accessed, for example on
162    /GitHub/, /repo.or.cz/, or on your own server.
163
164 3. Push your topic branches (and optionally the master branch) to your
165    public repository.
166
167    Define a remote for your public repository you push topics to.
168
169    : git remote add REMOTE URL-GOES-HERE
170
171    Push branches to the remote
172
173    : git push REMOTE BRANCH1 [BRANCH2 BRANCH3 ...]
174
175    e.g.
176
177    : git remote add github ssh://.../     # Done once to define the remote 'github'
178    : git push github my-topic
179
180 4. Do your work on topic-specific branches, using a branch name that
181    relates to what you are working on.
182
183 5. Often do
184
185    : git remote update
186
187    to pull commits from all defined remote repositories, in particular
188    the org-mode master at /repo.or.cz/.
189
190 6. When you have something workable, publish the git path and branch
191    name on the mailing list, so that people can test it and review
192    your work.
193
194 7. After your topic has been merged to the project master branch you
195    can delete the topic on your local and remote repositories.
196
197    : git branch -d NEWTOPIC
198    : git push REMOTE :NEWTOPIC
199
200 * Commit messages and ChangeLog entries
201
202 We have decided to no longer keep a ChangeLog file to record changes to
203 individual functions.  In a modern version control system like git,
204 ChangeLog is duplicating information that should be in the commit message,
205 and it is the main cause of merge conflicts.
206
207 Instead, the change log entry should be part of the commit message.  A
208 commit message should be constructed in the following way:
209
210 - Line 1 of the commit message should always be a short description of
211   the overall change.  Line 1 does /not/ get a dot at the end.
212 - Line 2 is an empty line
213 - In line 3, the ChangeLog entry should start, in a similar format as
214   in the old ChangeLog files, but without the author information
215   (which is part of the commit anyway).
216 - After the changelog, another empty line should come before any
217   additional information that the committer wishes to provide in order
218   to explain the patch.
219 - If the change is a minor change made by a committer without
220   copyright assignment to the FSF, the commit message should also
221   contain the cookie =TINYCHANGE= (anywhere in the message).  When we
222   later produce the ChangeLog file for Emacs, the change will be
223   marked appropriately.
224
225 Here is an example for such a message
226
227 #+begin_example
228   Capture: Fix the case of using a template file
229       
230   ,* lisp/org-capture.el (org-capture-set-plist): Make sure txt is a string
231   before calling `string-match'.
232   (org-capture-templates): Fix customization type.
233   ,* doc/org.texi (Capture): Document using a file for a template
234       
235   The problem here was that a wrong keyword was given in the
236   customization type.  This let to a string-match against a list value.
237   
238   Modified from a patch proposal by Johan Friis.
239   
240   TINYCHANGE
241 #+end_example
242
243 If you are using /magit.el/ in Emacs, The ChangeLog-like such entries are
244 easily made by pressing =C= in the diff listing.  Another option to make
245 the entries is to use `C-x 4 a' in the changed function.  This will create
246 entries in the ChangeLog file, and you can then cut and paste these to the
247 commit message and remove the indentation.
248
249 * Copyrighted contributors to Org-mode
250
251 Here is the list of people who have contributed actual code to the
252 Org-mode core.  Note that the manual contains a more extensive list
253 with acknowledgments, including contributed ideas!  The lists below
254 are mostly for house keeping, to help the maintainers keep track of
255 copyright issues.
256
257 ** Current contributors
258   :PROPERTIES:
259   :CUSTOM_ID: contributors_with_fsf_papers
260   :END:
261
262 Here is the list of people who signed the papers with the Free Software
263 Foundation and can now freely submit code to Org files that are included
264 within GNU Emacs:
265
266 1. Adam Elliott
267 2. Andreas Burtzlaff
268 3. Andy Steward
269 4. Anthony Lander
270 5. Baoqiu Cui
271 6. Barry Leonard Gidden
272 7. Bastien Guerry
273 8. Benjamin Andresen
274 9. Bernd Grobauer
275 10. Bernt Hansen
276 11. Brian James Gough
277 12. Carsten Dominik
278 13. Charles Sebold
279 14. Christian Egli
280 15. Christopher League
281 16. Christopher Miles Gray
282 17. Christopher Suckling
283 18. Dan Davison
284 19. Daniel M German
285 20. Daniel M. Hackney
286 21. David Maus
287 22. David O'Toole
288 23. Eric S. Fraga
289 24. Eric Schulte
290 25. Erik Iverson
291 26. Ian Barton
292 27. James TD Smith
293 28. Jan Böker
294 29. Jason Riedy
295 30. Jeffrey Ryan Horn
296 31. Joel Boehland
297 32. John Wiegley
298 33. Juan Pechiar
299 34. Julien Barnier
300 35. Julien Danjou
301 36. Konstantin Antipin
302 37. Lennart Borgman
303 38. Lukasz Stelmach
304 39. Magnus Henoch
305 40. Manuel Giraud
306 41. Martin Pohlack
307 42. Martyn Jago
308 43. Matt Lundin
309 44. Michael Gauland
310 45. Michael Sperber
311 46. Miguel A. Figueroa-Villanueva
312 47. Mikael Fornius
313 48. Nathan Neff
314 49. Nicolas Goaziou
315 50. Noorul Islam K M
316 51. Paul Sexton
317 52. Peter Jones
318 53. Phil Jackson
319 54. Philip Rooke
320 55. Piotr Zielinski
321 56. Puneeth Chaganti
322 57. Richard Klinda
323 58. Richard Riley
324 59. Ross Patterson
325 60. Russel Adams
326 61. Sacha Chua
327 62. Sebastian Rose
328 63. Sebastien Vauban
329 64. Seweryn Kokot
330 65. Stephen Eglen
331 66. Tassilo Horn
332 67. Thomas Baumann
333 68. Tokuya Kameshima
334 69. Tom Breton
335 70. Tomas Hlavaty
336 71. Ulf Stegemann
337 72. Zhang Weize
338
339 ** Processing
340
341 These people have been asked to sign the papers, and they are
342 currently considering it or a request is being processed by the FSF.
343
344 1. Chris Gray
345
346 ** Tiny Changes
347
348 These people have submitted tiny change patches that made it into Org
349 without FSF papers.  When they submit more, we need to get papers
350 eventually.  The limit is a cumulative change of 20 non-repetitive
351 change lines.  Details are given in [[http://www.gnu.org/prep/maintain/maintain.html#Legally-Significant ][this document]].
352
353 1. Robert P. Goldman
354 2. Andy Lutomirski
355
356 (this list may be incomplete - please help to complete it)
357
358 ** No FSF assignment
359
360 These people cannot or prefer to not sign the FSF copyright papers,
361 and we can only accept patches that do not change the core files (the
362 ones that are also in Emacs).
363
364 Luckily, this list is still empty.
365
366 #+BEGIN: timestamp :string "Last update: " :format "%Y-%m-%d @ %H:%M"
367
368 #+END: