Changelog example: Blank line between files
[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
299   ,* doc/org.texi (Capture): Document using a file for a template.
300       
301   The problem here was that a wrong keyword was given in the
302   customization type.  This let to a string-match against a list value.
303   
304   Modified from a patch proposal by Johan Friis.
305   
306   TINYCHANGE
307 #+end_example
308
309 If you are using /magit.el/ in Emacs, The ChangeLog-like such entries are
310 easily made by pressing =C= in the diff listing.  Another option to make
311 the entries is to use `C-x 4 a' in the changed function.  This will create
312 entries in the ChangeLog file, and you can then cut and paste these to the
313 commit message and remove the indentation.
314
315 * Copyrighted contributors to Org-mode
316
317 Here is the list of people who have contributed actual code to the
318 Org-mode core.  Note that the manual contains a more extensive list
319 with acknowledgments, including contributed ideas!  The lists below
320 are mostly for house keeping, to help the maintainers keep track of
321 copyright issues.
322
323 ** Current contributors
324   :PROPERTIES:
325   :CUSTOM_ID: contributors_with_fsf_papers
326   :END:
327
328 Here is the list of people who signed the papers with the Free Software
329 Foundation and can now freely submit code to Org files that are included
330 within GNU Emacs:
331
332 1. Aaron Ecay
333 2. Abdó Roig-Maranges
334 3. Achim Gratz
335 4. Adam Elliott
336 5. Adam Spiers
337 6. Alan Schmitt
338 7. Andreas Burtzlaff
339 8. Andreas Leha
340 9. Andrew Hyatt
341 10. Andrzej Lichnerowicz
342 11. Andy Steward
343 12. Anthony John Day
344 13. Anthony Lander
345 14. Baoqiu Cui
346 15. Barry Leonard Gidden
347 16. Bastien Guerry
348 17. Benjamin Andresen
349 18. Bernd Grobauer
350 19. Bernt Hansen
351 20. Brian James Gough
352 21. Carsten Dominik
353 22. Charles Sebold
354 23. Christian Egli
355 24. Christian Moe
356 25. Christopher League
357 26. Christopher Miles Gray
358 27. Christopher Schmidt
359 28. Christopher Suckling
360 29. Dan Davison
361 30. Daniel M German
362 31. Daniel M. Hackney
363 32. David Arroyo Menéndez
364 33. David Maus
365 34. David O'Toole
366 35. Dmitry Antipov
367 36. Eric Abrahamsen
368 37. Eric S. Fraga
369 38. Eric Schulte
370 39. Erik Iverson
371 40. Ethan Ligon
372 41. Feng Shu
373 42. Francesco Pizzolante
374 43. Gary Oberbrunner
375 44. Georg Lehner
376 45. George Kettleborough
377 46. Giovanni Ridolfi
378 47. Grégoire Jadi (aka Daimrod)
379 48. Henning Dietmar Weiss
380 49. Ian Barton
381 50. Ilya Shlyakhter
382 51. Ippei Furuhashi
383 52. James TD Smith
384 53. Jan Böcker
385 54. Jarmo Hurri
386 55. Jason Riedy
387 56. Jay Kerns
388 57. Jeffrey Ryan Horn
389 58. Joel Boehland
390 59. John Wiegley
391 60. Jonas Bernoulli
392 61. Jonathan Leech-Pepin
393 62. Juan Pechiar
394 63. Julian Gehring
395 64. Julien Barnier
396 65. Julien Danjou
397 66. Justus Piater
398 67. Kodi Arfer
399 68. Konstantin Antipin
400 69. Lawrence Mitchell
401 70. Le Wang
402 71. Lennart Borgman
403 72. Luis Anaya
404 73. Lukasz Stelmach
405 74. Madan Ramakrishnan
406 75. Magnus Henoch
407 76. Manuel Giraud
408 77. Martin Pohlack
409 78. Martyn Jago
410 79. Matt Lundin
411 80. Max Mikhanosha
412 81. Michael Albinus
413 82. Michael Brand
414 83. Michael Gauland
415 84. Michael Sperber
416 85. Miguel A. Figueroa-Villanueva
417 86. Mikael Fornius
418 87. Moritz Ulrich
419 88. Nathan Neff
420 89. Nicholas Dokos
421 90. Nicolas Goaziou
422 91. Nicolas Richard
423 92. Niels Giessen
424 93. Noorul Islam K M
425 94. Oleh Krehel
426 95. Paul Sexton
427 96. Pedro Alexandre Marcelino Costa da Silva
428 97. Peter Jones
429 98. Phil Jackson
430 99. Philip Rooke
431 100. Pieter Praet
432 101. Piotr Zielinski
433 102. Puneeth Chaganti
434 103. Rasmus Pank Roulund
435 104. Richard Klinda
436 105. Richard Riley
437 106. Rick Frankel
438 107. Rüdiger Sonderfeld
439 108. Russel Adams
440 109. Ryo Takaishi
441 110. Sacha Chua
442 111. Samuel Loury
443 112. Sebastian Rose
444 113. Sebastien Vauban
445 114. Sergey Litvinov
446 115. Seweryn Kokot
447 116. Stephen Eglen
448 117. Suvayu Ali
449 118. T.F. Torrey
450 119. Tassilo Horn
451 120. Thomas Baumann
452 121. Thomas Holst
453 122. Thomas S. Dye
454 123. Thorsten Jolitz
455 124. Tim Burt
456 125. Toby Cubitt
457 126. Tokuya Kameshima
458 127. Tom Breton
459 128. Tomas Hlavaty
460 129. Tony Day
461 130. Ulf Stegemann
462 131. Vitalie Spinu
463 132. Yann Hodique
464 133. Yasushi Shoji
465 134. Yoshinari Nomura
466 135. Zhang Weize
467
468 ** Processing
469
470 These people have been asked to sign the papers, and they are
471 currently considering it or a request is being processed by the FSF.
472
473 - Bill Wishon
474 - Mats Kindahl (as of 2013-04-06) for [[http://mid.gmane.org/513BAB7D.1000603%2540oracle.com][this patch]]
475 - Georg Lehner (as of 2013-06-27)
476 - Kodi Arfer (as of 2013-06-29)
477
478 ** Tiny Changes
479
480 These people have submitted tiny change patches that made it into Org
481 without FSF papers.  When they submit more, we need to get papers
482 eventually.  The limit is a cumulative change of 20 non-repetitive
483 change lines.  Details are given in [[http://www.gnu.org/prep/maintain/maintain.html#Legally-Significant ][this document]].
484
485 1. Andy Lutomirski
486 2. Aurélien Aptel
487 3. Brice Waegenire
488 4. Craig Tanis
489 5. Gustav Wikström
490 6. Ivan Vilata i Balaguer
491 7. John Foerch
492 8. Jonas Hörsch
493 9. Joost Diepenmaat
494 10. Kodi Arfer
495 11. Muchenxuan Tong
496 12. Myles English
497 13. Rafael Laboissiere
498 14. Robert P. Goldman
499 15. Trevor Murphy
500 16. Viktor Rosenfeld
501
502 (This list may be incomplete - please help completing it.)
503
504 ** No FSF assignment
505
506 These people cannot or prefer to not sign the FSF copyright papers,
507 and we can only accept patches that do not change the core files (the
508 ones that are also in Emacs).
509
510 Luckily, this list is still empty.
511
512 #+BEGIN: timestamp :string "Last update: " :format "%Y-%m-%d @ %H:%M"
513
514 #+END: