7ae270e739d4d0d39382ea5d316120d6a7e51d8f
[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 S. Fraga
386 36. Eric Schulte
387 37. Erik Iverson
388 38. Ethan Ligon
389 39. Feng Shu
390 40. Gary Oberbrunner
391 41. George Kettleborough
392 42. Giovanni Ridolfi
393 43. Grégoire Jadi (aka Daimrod)
394 44. Henning Dietmar Weiss
395 45. Ian Barton
396 46. Ilya Shlyakhter
397 47. Ippei Furuhashi
398 48. James TD Smith
399 49. Jan Böcker
400 50. Jarmo Hurri
401 51. Jason Riedy
402 52. Jay Kerns
403 53. Jeffrey Ryan Horn
404 54. Joel Boehland
405 55. John Wiegley
406 56. Jonas Bernoulli
407 57. Jonathan Leech-Pepin
408 58. Juan Pechiar
409 59. Julian Gehring
410 60. Julien Barnier
411 61. Julien Danjou
412 62. Justus Piater
413 63. Konstantin Antipin
414 64. Lawrence Mitchell
415 65. Le Wang
416 66. Lennart Borgman
417 67. Luis Anaya
418 68. Lukasz Stelmach
419 69. Madan Ramakrishnan
420 70. Magnus Henoch
421 71. Manuel Giraud
422 72. Martin Pohlack
423 73. Martyn Jago
424 74. Matt Lundin
425 75. Max Mikhanosha
426 76. Michael Brand
427 77. Michael Gauland
428 78. Michael Sperber
429 79. Miguel A. Figueroa-Villanueva
430 80. Mikael Fornius
431 81. Moritz Ulrich
432 82. Nathan Neff
433 83. Nicolas Goaziou
434 84. Nicolas Richard
435 85. Niels Giessen
436 86. Noorul Islam K M
437 87. Paul Sexton
438 88. Peter Jones
439 89. Phil Jackson
440 90. Philip Rooke
441 91. Pieter Praet
442 92. Piotr Zielinski
443 93. Puneeth Chaganti
444 94. Richard Klinda
445 95. Richard Riley
446 96. Rick Frankel
447 97. Ross Patterson
448 98. Russel Adams
449 99. Ryo Takaishi
450 100. Sacha Chua
451 101. Samuel Loury
452 102. Sebastian Rose
453 103. Sebastien Vauban
454 104. Sergey Litvinov
455 105. Seweryn Kokot
456 106. Stephen Eglen
457 107. T.F. Torrey
458 108. Tassilo Horn
459 109. Thomas Baumann
460 110. Thomas Holst
461 111. Thomas S. Dye
462 112. Thorsten Jolitz
463 113. Tim Burt
464 114. Toby Cubitt
465 115. Tokuya Kameshima
466 116. Tom Breton
467 117. Tomas Hlavaty
468 118. Tony Day
469 119. Ulf Stegemann
470 120. Yann Hodique
471 121. Zhang Weize
472
473 ** Processing
474
475 These people have been asked to sign the papers, and they are
476 currently considering it or a request is being processed by the FSF.
477
478 - Bill Wishon
479 - Francesco Pizzolante (as of 2013-01-31)
480
481 ** Tiny Changes
482
483 These people have submitted tiny change patches that made it into Org
484 without FSF papers.  When they submit more, we need to get papers
485 eventually.  The limit is a cumulative change of 20 non-repetitive
486 change lines.  Details are given in [[http://www.gnu.org/prep/maintain/maintain.html#Legally-Significant ][this document]].
487
488 1. Alan Schmitt
489 2. Andy Lutomirski
490 3. Ivan Vilata i Balaguer
491 4. John Foerch
492 5. Myles English
493 6. Rafael Laboissiere
494 7. Robert P. Goldman
495 9. Muchenxuan Tong
496
497 (This list may be incomplete - please help completing it.)
498
499 ** No FSF assignment
500
501 These people cannot or prefer to not sign the FSF copyright papers,
502 and we can only accept patches that do not change the core files (the
503 ones that are also in Emacs).
504
505 Luckily, this list is still empty.
506
507 #+BEGIN: timestamp :string "Last update: " :format "%Y-%m-%d @ %H:%M"
508
509 #+END: