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