org-contribute.org: Add Eric Abrahamsen to the list of FSF-signed contributors
[worg.git] / org-contribute.org
1 #+TITLE:      How to contribute to Org?
2 #+AUTHOR:     Worg people
3 #+EMAIL:      mdl AT imapmail DOT org
4 #+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
5 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
6 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
7 #+TAGS:       Write(w) Update(u) Fix(f) Check(c) 
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 total
38   contribution (all patches you submit) should change /less than 15 lines/
39   (See the [[http://bzr.savannah.gnu.org/lh/emacs/trunk/annotate/head:/etc/CONTRIBUTE][etc/CONTRIBUTE file in GNU Emacs]].)  If you contribute more, you
40   have to assign the copyright of your contribution to the Free Software
41   Foundation (see below).
42   
43 - you can submit Org *add-ons* -- there are many Org add-ons.  The best way
44   is to submit your code to the mailing list to discuss it with people.  If
45   it is useful, you might consider contributing it to the =CONTRIB/=
46   directory in the git repository.
47
48 - you can submit material to the *Worg* website -- This website is made of
49   Org files that you can contribute to.  Learn what Worg is [[file:worg-about.org][about]] and how
50   to contribute to it [[file:worg-git.org][through git]].
51
52 * Copyright issues when contributing to Emacs org-mode
53
54 Org is made of many files.  Most of them are also distributed as part
55 of GNU Emacs.  These files are called the /Org core/, and they are all
56 copyrighted by the [[http://www.fsf.org][Free Software Foundation, Inc]].  If you consider
57 contributing to these files, your first need to grant the right to
58 include your works in GNU Emacs to the FSF.  For this you need to
59 complete [[http://orgmode.org/request-assign-future.txt][this form]], and send it to [[mailto:assign@gnu.org][assign@gnu.org]].  The FSF will send
60 you the assignment contract that both you and the FSF will sign.
61 Please let the Org-mode maintainer know when this process is complete.
62 Some people consider this assignment process a hassle.  I don't want
63 to discuss this in detail here - there are some good reasons for
64 getting the copyright registered, an example is discussed in this
65 [[http://twit.tv/floss117][FLOSS weekly podcast]].  Furthermore, by playing according to the Emacs
66 rules, we gain the fantastic advantage that every version of Emacs
67 ships with Org-mode already fully built in.  So please consider doing
68 this - it makes our work as maintainers so much easier, because we can
69 then take your patches without any additional work.
70
71 If you want to learn more about /why/ copyright assignments are
72 collected, read this: [[http://www.gnu.org/licenses/why-assign.html][Why the FSF gets copyright assignments from
73 contributors?]]
74
75 By submitting patches to emacs-orgmode@gnu.org, or by pushing changes
76 to the Org-mode repository, you are placing these changes under the
77 same licensing terms as those under which GNU Emacs is published.
78
79 #+begin_example
80  ;; GNU Emacs is free software: you can redistribute it and/or modify
81  ;; it under the terms of the GNU General Public License as published by
82  ;; the Free Software Foundation, either version 3 of the License, or
83  ;; (at your option) any later version.
84 #+end_example
85
86 If at the time you submit or push these changes you do have active
87 copyright assignment papers with the FSF, for future changes to either
88 Org-mode or to Emacs, this means that copyright to these changes is
89 automatically transferred to the FSF.  The Org-mode repository is seen
90 as upstream repository for Emacs, anything contained in it can
91 potentially end up in Emacs.  If you do not have signed papers with
92 the FSF, only changes to files in the =contrib/= part of the repository
93 will be accepted, as well as very minor changes (so-called /tiny
94 changes/) to core files.  We will ask you to sign FSF papers at the
95 moment we attempt to move a =contrib/= file into the Org core, or into
96 Emacs.
97
98 * For Org developers
99 :PROPERTIES:
100 :CUSTOM_ID: devs
101 :END:
102
103 1. Send your public key to [[mailto:jasondunsmore%20AT%20gmail%20DOT%20com][Jason Dunsmore]] or Org's maintainer.
104
105 2. Wait for confirmation that your public key has been added to the server.
106
107 3. Clone =org-mode.git= repository like this:
108    : ~$ git clone orgmode@orgmode.org:org-mode.git
109
110 4. Commit your changes.
111
112 5. Run =make test=
113
114 6. If the tests pass, push your changes.
115
116 If you are undertaking big changes, please create a dedicated branch for
117 them.
118
119 * For Org contributors: preferred way of submitting patches
120
121 ** Coding conventions
122
123 Org is part of Emacs, so any contribution should follow the [[http://www.gnu.org/software/emacs/elisp/html_node/Coding-Conventions.html][GNU Emacs Lisp
124 coding conventions]] described in Emacs manual.
125
126 ** Sending patch with git
127
128 Org-mode is developed using /git/ as the version control system.  Git
129 provides an amazing framework to collaborate on a project.  Git can be used
130 to make patches and send them via email -- this is perfectly fine for major
131 and minor changes.
132
133 When sending a patch (either using =git diff= or =git format-patch=) please
134 *always add a properly formatted Emacs ChangeLog entry*.  See [[id:c526dfd7-2b0c-4b66-9deb-6e442e48708c][this section]]
135 for details on how to create such a ChangeLog.
136
137 ** Patches get caught on patchwork
138
139 As long as these patches are formatted properly, they will be automatically
140 registered at [[http://patchwork.newartisans.com/project/org-mode][John Wiegley's patchwork server]] and will then be accepted,
141 rejected, or sent back to the author with a request for modification.
142
143 Patchwork assumes there is *only one patch per email* and will not catch
144 more than one patch -- so please send multiple patches in separate emails.
145
146 In this context, "formatted properly" means that the patches are included
147 either plainly in the mail text, or as text attachments (mime-type text,
148 subtypes "x-patch", "x-diff", or "plain").  In particular, binary types or,
149 even worse, "application/octet-stream" (the asinine default of some mail
150 programs) are *not* going to be recognized.  Please find out how to
151 convince your mail program to send proper attachments.  Also, if you
152 include the patch inline, please make sure that your mail program does not
153 reformat it (although there are plenty of places further down the line
154 where that can happen, unfortunately). If you attach the patch, then
155 reformatting is not a problem.
156
157 ** Sending commits
158
159 For every patch you send, we suggest to use =git format-patch=.
160
161 This is easy for small patches and more consequent ones.  Sometimes, you
162 might even want to work in several steps and send each commit separately.
163 Here is the suggested workflow:
164
165 #+begin_quote
166 :   ~$ git pull                 # make sure your repo is up to date
167 :   ~$ git branch my-changes    # create a new branch from master
168 :   ~$ git checkout my-changes  # switch to this new branch
169
170   ... make some changes (1) ...
171
172 :   ~$ git commit -m "This is change (1)"  # Commit your change
173
174   ... make another change (2) ...
175
176 :   ~$ git commit -m "This is change (2)"  # Commit your change
177 :   ~$ git format-patch master             # Creates two patches
178
179   ... Then two patches for your two commits are ready to be sent to the
180   list and detected by the patchwork server.
181 #+end_quote
182
183 Write useful commit messages: please provide 1) a reason for it in your
184 email and 2) a ChangeLog entry in the commit message (see [[id:c526dfd7-2b0c-4b66-9deb-6e442e48708c][this section]] on
185 how to format a ChangeLog entry.)
186
187 ** Sending quick fixes for testing purpose
188
189 If you want to send a quick fix that needs to be further tested by other
190 people (before you submit a real patch), here is how you can do:
191
192 #+begin_quote
193   This command will make a patch between the staging area (in your
194   computer), and the file you modified:
195
196   : git diff -p org-whatever.el > org-whatever.el.diff
197
198   If you already committed your changes to your index (staging area), then
199   you should compare against a particular branch (in this example,
200   origin/master):
201
202   : git diff -p origin/master org-whatever.el > org-whatever.el.diff
203
204   You email the output to the mailing list, adding =[PATCH]= to the
205   subject, and description of what you fixed or changed.
206 #+end_quote
207
208 Note that small patches sent like this still need to have a ChangeLog entry
209 to be applied.  If your patch looks good to you, it's always better to send
210 a patch through =git format-patch=.
211
212 ** Sharing changes from a public branch
213
214 For more significant contributions, the best way to submit patches is
215 through public branches of your repository clone.
216
217 1. Clone our git repository at =http://orgmode.org/w/org-mode.git=.
218    You can clone using any of the commands below.
219
220    : git clone git://orgmode.org/org-mode.git
221    : git clone http://orgmode.org/org-mode.git
222
223    The url using the git protocol is preferred. If you are behind a
224    firewall that blocks ~git://~, you can use the http url.
225
226 2. Create a repository that can be publicly accessed, for example on
227    /GitHub/, /repo.or.cz/, or on your own server.
228
229 3. Push your topic branches (and optionally the master branch) to your
230    public repository.
231
232    Define a remote for your public repository you push topics to.
233
234    : git remote add REMOTE URL-GOES-HERE
235
236    Push branches to the remote
237
238    : git push REMOTE BRANCH1 [BRANCH2 BRANCH3 ...]
239
240    e.g.
241
242    : git remote add github ssh://.../     # Done once to define the remote 'github'
243    : git push github my-topic
244
245 4. Do your work on topic-specific branches, using a branch name that
246    relates to what you are working on.
247
248 5. Often do
249
250    : git remote update
251
252    to pull commits from all defined remote repositories, in particular
253    the org-mode master at /repo.or.cz/.
254
255 6. When you have something workable, publish the git path and branch
256    name on the mailing list, so that people can test it and review
257    your work.
258
259 7. After your topic has been merged to the project master branch you
260    can delete the topic on your local and remote repositories.
261
262    : git branch -d NEWTOPIC
263    : git push REMOTE :NEWTOPIC
264
265 The instructions above are generally useful to let people test new features
266 before sending the patch series to the mailing list, but the patches remain
267 the preferred way of receiving contributions.
268
269 * Commit messages and ChangeLog entries
270   :PROPERTIES:
271   :ID:       c526dfd7-2b0c-4b66-9deb-6e442e48708c
272   :END:
273
274 We have decided to no longer keep a ChangeLog file to record changes to
275 individual functions.  In a modern version control system like git,
276 ChangeLog is duplicating information that should be in the commit message,
277 and it is the main cause of merge conflicts.
278
279 Instead, the change log entry should be part of the commit message.  A
280 commit message should be constructed in the following way:
281
282 - Line 1 of the commit message should always be a short description of the
283   overall change.  Line 1 does /not/ get a dot at the end and does not
284   start with a star.
285
286 - Line 2 is an empty line.
287
288 - In line 3, the ChangeLog entry should start, in a similar format as in
289   the old ChangeLog files, but without the author information (which is
290   part of the commit anyway).
291
292 - After the changelog, another empty line should come before any additional
293   information that the committer wishes to provide in order to explain the
294   patch.
295
296 - If the change is a minor change made by a committer without copyright
297   assignment to the FSF, the commit message should also contain the cookie
298   =TINYCHANGE= (anywhere in the message).  When we later produce the
299   ChangeLog file for Emacs, the change will be marked appropriately.
300
301 - Variables and functions names are quoted like =`this'= (backquote and
302   single quote).
303
304 - Sentences should be separated by two spaces.
305
306 - Sentences should start with an uppercase letter.
307
308 - Avoid the passive form: i.e., use "change" instead of "changed".
309
310 Here is an example for such a message:
311
312 #+begin_example
313   Capture: Fix the case of using a template file
314       
315   ,* lisp/org-capture.el (org-capture-set-plist): Make sure txt is a
316   string before calling `string-match'.
317   (org-capture-templates): Fix customization type.
318   ,* doc/org.texi (Capture): Document using a file for a template.
319       
320   The problem here was that a wrong keyword was given in the
321   customization type.  This let to a string-match against a list value.
322   
323   Modified from a patch proposal by Johan Friis.
324   
325   TINYCHANGE
326 #+end_example
327
328 If you are using /magit.el/ in Emacs, The ChangeLog-like such entries are
329 easily made by pressing =C= in the diff listing.  Another option to make
330 the entries is to use `C-x 4 a' in the changed function.  This will create
331 entries in the ChangeLog file, and you can then cut and paste these to the
332 commit message and remove the indentation.
333
334 * Copyrighted contributors to Org-mode
335
336 Here is the list of people who have contributed actual code to the
337 Org-mode core.  Note that the manual contains a more extensive list
338 with acknowledgments, including contributed ideas!  The lists below
339 are mostly for house keeping, to help the maintainers keep track of
340 copyright issues.
341
342 ** Current contributors
343   :PROPERTIES:
344   :CUSTOM_ID: contributors_with_fsf_papers
345   :END:
346
347 Here is the list of people who signed the papers with the Free Software
348 Foundation and can now freely submit code to Org files that are included
349 within GNU Emacs:
350
351 1. Aaron Ecay
352 2. Abdó Roig-Maranges
353 3. Achim Gratz
354 4. Adam Elliott
355 5. Adam Spiers
356 6. Alan Schmitt
357 7. Andreas Burtzlaff
358 8. Andreas Leha
359 9. Andrew Hyatt
360 10. Andrzej Lichnerowicz
361 11. Andy Steward
362 12. Anthony John Day
363 13. Anthony Lander
364 14. Baoqiu Cui
365 15. Barry Leonard Gidden
366 16. Bastien Guerry
367 17. Benjamin Andresen
368 18. Bernd Grobauer
369 19. Bernt Hansen
370 20. Brian James Gough
371 21. Carsten Dominik
372 22. Charles Sebold
373 23. Christian Egli
374 24. Christian Moe
375 25. Christopher League
376 26. Christopher Miles Gray
377 27. Christopher Schmidt
378 28. Christopher Suckling
379 29. Dan Davison
380 30. Daniel M German
381 31. Daniel M. Hackney
382 32. David Maus
383 33. David O'Toole
384 34. Dmitry Antipov
385 35. Eric Abrahamsen
386 36. Eric S. Fraga
387 37. Eric Schulte
388 38. Erik Iverson
389 39. Ethan Ligon
390 40. Feng Shu
391 41. Gary Oberbrunner
392 42. George Kettleborough
393 43. Giovanni Ridolfi
394 44. Grégoire Jadi (aka Daimrod)
395 45. Henning Dietmar Weiss
396 46. Ian Barton
397 47. Ilya Shlyakhter
398 48. Ippei Furuhashi
399 49. James TD Smith
400 50. Jan Böcker
401 51. Jarmo Hurri
402 52. Jason Riedy
403 53. Jay Kerns
404 54. Jeffrey Ryan Horn
405 55. Joel Boehland
406 56. John Wiegley
407 57. Jonas Bernoulli
408 58. Jonathan Leech-Pepin
409 59. Juan Pechiar
410 60. Julian Gehring
411 61. Julien Barnier
412 62. Julien Danjou
413 63. Justus Piater
414 64. Konstantin Antipin
415 65. Lawrence Mitchell
416 66. Le Wang
417 67. Lennart Borgman
418 68. Luis Anaya
419 69. Lukasz Stelmach
420 70. Madan Ramakrishnan
421 71. Magnus Henoch
422 72. Manuel Giraud
423 73. Martin Pohlack
424 74. Martyn Jago
425 75. Matt Lundin
426 76. Max Mikhanosha
427 77. Michael Brand
428 78. Michael Gauland
429 79. Michael Sperber
430 80. Miguel A. Figueroa-Villanueva
431 81. Mikael Fornius
432 82. Moritz Ulrich
433 83. Nathan Neff
434 84. Nicolas Goaziou
435 85. Nicolas Richard
436 86. Niels Giessen
437 87. Noorul Islam K M
438 88. Paul Sexton
439 89. Peter Jones
440 90. Phil Jackson
441 91. Philip Rooke
442 92. Pieter Praet
443 93. Piotr Zielinski
444 94. Puneeth Chaganti
445 95. Richard Klinda
446 96. Richard Riley
447 97. Rick Frankel
448 98. Ross Patterson
449 99. Russel Adams
450 100. Ryo Takaishi
451 101. Sacha Chua
452 102. Samuel Loury
453 103. Sebastian Rose
454 104. Sebastien Vauban
455 105. Sergey Litvinov
456 106. Seweryn Kokot
457 107. Stephen Eglen
458 108. T.F. Torrey
459 109. Tassilo Horn
460 110. Thomas Baumann
461 111. Thomas Holst
462 112. Thomas S. Dye
463 113. Thorsten Jolitz
464 114. Tim Burt
465 115. Toby Cubitt
466 116. Tokuya Kameshima
467 117. Tom Breton
468 118. Tomas Hlavaty
469 119. Tony Day
470 120. Ulf Stegemann
471 121. Yann Hodique
472 122. Zhang Weize
473
474 ** Processing
475
476 These people have been asked to sign the papers, and they are
477 currently considering it or a request is being processed by the FSF.
478
479 - Bill Wishon
480 - Francesco Pizzolante (as of 2013-01-31)
481
482 ** Tiny Changes
483
484 These people have submitted tiny change patches that made it into Org
485 without FSF papers.  When they submit more, we need to get papers
486 eventually.  The limit is a cumulative change of 20 non-repetitive
487 change lines.  Details are given in [[http://www.gnu.org/prep/maintain/maintain.html#Legally-Significant ][this document]].
488
489 1. Alan Schmitt
490 2. Andy Lutomirski
491 3. Ivan Vilata i Balaguer
492 4. John Foerch
493 5. Myles English
494 6. Rafael Laboissiere
495 7. Robert P. Goldman
496 9. Muchenxuan Tong
497
498 (This list may be incomplete - please help completing it.)
499
500 ** No FSF assignment
501
502 These people cannot or prefer to not sign the FSF copyright papers,
503 and we can only accept patches that do not change the core files (the
504 ones that are also in Emacs).
505
506 Luckily, this list is still empty.
507
508 #+BEGIN: timestamp :string "Last update: " :format "%Y-%m-%d @ %H:%M"
509
510 #+END: