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