Add Toby Cubitt to the list of signed contributors.
[worg.git] / org-contribute.org
1 #+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
2 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
3 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
4 #+TAGS:       Write(w) Update(u) Fix(f) Check(c) 
5 #+TITLE:      How to contribute to Org?
6 #+AUTHOR:     Worg people
7 #+EMAIL:      mdl AT imapmail DOT org
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 #+index: Contribute
18
19 * Types of contributions
20
21 Every contribution to Org is very welcome.  Here is a list of areas where
22 your contribution will be useful:
23
24 - you can submit *bug reports* -- Before sending a bug report, make sure
25   you have read this section of Org's manual: [[http://orgmode.org/org.html#Feedback][Feedback]]  You can also read
26   this great text: "[[http://www.chiark.greenend.org.uk/~sgtatham/bugs.html][How to Send Bug Reports Effectively]]"
27
28 - you can submit *feature requests* -- Org is already mature, but new ideas
29   keep popping up.  If you want to request a feature, it might be a good
30   idea to have a look at the current [[http://orgmode.org/worg/org-issues.html][Issue tracking file]] which captures
31   both bug reports and feature requests.  Or dig into the mailing list for
32   possible previous discussions about your idea.  If you cannot find back
33   your idea, formulate it as detailed as possible, if possible with
34   examples, and send it to the mailing list.
35
36 - you can submit *patches* -- You can submit patches to the mailing list.
37   See the [[For Org contributors: preferred way of submitting patches][Preferred way of submitting patches]] section for details.
38
39   If your patch is against a file that is part of Emacs, then your total
40   contribution (all patches you submit) should change /less than 15 lines/
41   (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
42   have to assign the copyright of your contribution to the Free Software
43   Foundation (see below).
44   
45 - you can submit Org *add-ons* -- there are many Org add-ons.  The best way
46   is to submit your code to the mailing list to discuss it with people.  If
47   it is useful, you might consider contributing it to the =CONTRIB/=
48   directory in the git repository.
49
50 - you can submit material to the *Worg* website -- This website is made of
51   Org files that you can contribute to.  Learn what Worg is [[file:worg-about.org][about]] and how
52   to contribute to it [[file:worg-git.org][through git]].
53
54 * Copyright issues when contributing to Emacs org-mode
55
56 #+index: Copyright
57 #+index: FSF
58 #+index: Assignment
59
60 Org is made of many files.  Most of them are also distributed as part of
61 GNU Emacs.  These files are called the /Org core/, and they are all
62 copyrighted by the [[http://www.fsf.org][Free Software Foundation, Inc]].  If you consider
63 contributing to these files, your first need to grant the right to include
64 your works in GNU Emacs to the FSF.  For this you need to complete [[http://orgmode.org/request-assign-future.txt][this
65 form]], send it to [[mailto:assign@gnu.org][assign@gnu.org]], and tell the Org-mode maintainer when this
66 process is complete.  Some people consider this a hassle.  I don't want to
67 discuss this in detail here - there are some good reasons for getting the
68 copyright registered, an example is discussed in this [[http://twit.tv/floss117][FLOSS weekly
69 podcast]].  Furthermore, by playing according to the Emacs rules, we gain the
70 fantastic advantage that every version of Emacs ships with Org-mode already
71 fully built in.  So please consider doing this - it makes our work as
72 maintainers so much easier, because we can then take your patches without
73 any additional work.
74
75 If you want to learn more about /why/ copyright assignments are collected,
76 read this: [[http://www.gnu.org/licenses/why-assign.html][Why the FSF gets copyright assignments from contributors?]]
77
78 * For Org developers
79   :PROPERTIES:
80   :CUSTOM_ID: devs
81   :END:
82
83 #+index: Public key
84
85 1. Send your public key to [[mailto:jasondunsmore%20AT%20gmail%20DOT%20com][Jason Dunsmore]].
86
87 2. Wait for confirmation that your public key has been added to the server.
88
89 3. Clone =org-mode.git= repository like this:
90    : ~$ git clone orgmode@orgmode.org:org-mode.git
91
92 4. Commit your changes and push them.
93
94 If you are undertaking big changes, please create a dedicated branch for
95 them.
96
97 * For Org contributors: preferred way of submitting patches
98
99 ** Coding conventions
100
101 #+index: Coding!Conventions
102
103 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
104 coding conventions]] described in Emacs manual.
105
106 ** Sending patch with git
107
108 #+index: Patch
109 #+index: Git
110
111 Org-mode is developed using /git/ as the version control system.  Git
112 provides an amazing framework to collaborate on a project.  Git can be used
113 to make patches and send them via email -- this is perfectly fine for minor
114 changes.
115
116 ** Patches get caught on patchwork
117
118 #+index: Patch
119 #+index: Patchwork
120
121 As long as these patches are formatted properly, they will be automatically
122 registered at [[http://patchwork.newartisans.com/project/org-mode][John Wiegley's patchwork server]] and will then be accepted,
123 rejected, or sent back to the author with a request for modification.
124
125 Patchwork assumes there is *only one patch per email* and will not catch
126 more than one patch -- so please send multiple patches in separate emails.
127
128 In this context, "formatted properly" means that the patches are included
129 either plainly in the mail text, or as text attachments (mime-type text,
130 subtypes "x-patch", "x-diff", or "plain").  In particular, binary types or,
131 even worse, "application/octet-stream" (the asinine default of some mail
132 programs) are *not* going to be recognized.  Please find out how to
133 convince your mail program to send proper attachments.  Also, if you
134 include the patch inline, please make sure that your mail program does not
135 reformat it (although there are plenty of places further down the line
136 where that can happen, unfortunately). If you attach the patch, then
137 reformatting is not a problem.
138
139 ** Sending quick fixes
140
141 #+index: Fixes
142
143 #+begin_quote
144   This command will make a patch between the staging area (in your
145   computer), and the file you modified:
146
147   : git diff -p org-whatever.el > org-whatever.el.diff
148
149   If you already committed your changes to your index (staging area), then
150   you should compare against a particular branch (in this example,
151   origin/master):
152
153   : git diff -p origin/master org-whatever.el > org-whatever.el.diff
154
155   You email the output to the mailing list, adding =[PATCH]= to the
156   subject, and description of what you fixed or changed.
157 #+end_quote
158
159 ** Sending commits
160
161 #+index: Commits
162
163 For more significant changes, you might want to work in several steps and
164 send each commit separately.  Here is the suggested workflow
165
166 #+begin_quote
167 :   ~$ git pull                 # make sure your repo is up to date
168 :   ~$ git branch my-changes    # create a new branch
169 :   ~$ git checkout my-changes  # switch to this new branch
170
171   ... make some changes (1) ...
172
173 :   ~$ git commit -m "This is change (1)"  # Commit your change
174
175   ... make another change (2) ...
176
177 :   ~$ git commit -m "This is change (2)"  # Commit your change
178 :   ~$ git format-patch master             # Creates two patches
179
180   ... Then two patches for your two commits are ready to be sent to the
181   list and detected by the patchwork server.
182 #+end_quote
183
184 Write useful commit messages: unless your change is very small, please
185 provide 1) a reason for it in your email and 2) a ChangeLog entry in the
186 commit message.
187
188 ** Sharing changes from a public branch
189
190 #+index: Git!Branch
191
192 For more significant contributions, the best way to submit patches is
193 through public branches of your repository clone.
194
195 1. Clone our git repository at =git://orgmode.org/org-mode.git= or 
196    =http://orgmode.org/org-mode.git=
197
198 2. Create a repository that can be publicly accessed, for example on
199    /GitHub/, /repo.or.cz/, or on your own server.
200
201 3. Push your topic branches (and optionally the master branch) to your
202    public repository.
203
204    Define a remote for your public repository you push topics to.
205
206    : git remote add REMOTE URL-GOES-HERE
207
208    Push branches to the remote
209
210    : git push REMOTE BRANCH1 [BRANCH2 BRANCH3 ...]
211
212    e.g.
213
214    : git remote add github ssh://.../     # Done once to define the remote 'github'
215    : git push github my-topic
216
217 4. Do your work on topic-specific branches, using a branch name that
218    relates to what you are working on.
219
220 5. Often do
221
222    : git remote update
223
224    to pull commits from all defined remote repositories, in particular the
225    org-mode master at /orgmode.org/ (or its clone at /repo.or.cz/.)
226
227 6. When you have something workable, publish the git path and branch
228    name on the mailing list, so that people can test it and review
229    your work.
230
231 7. After your topic has been merged to the project master branch you
232    can delete the topic on your local and remote repositories.
233
234    : git branch -d NEWTOPIC
235    : git push REMOTE :NEWTOPIC
236
237 * Commit messages and ChangeLog entries
238
239 #+index: ChangeLog
240 #+index: Commit!Message
241
242 We have decided to no longer keep a ChangeLog file to record changes to
243 individual functions.  In a modern version control system like git,
244 ChangeLog is duplicating information that should be in the commit message,
245 and it is the main cause of merge conflicts.
246
247 Instead, the change log entry should be part of the commit message.  A
248 commit message should be constructed in the following way:
249
250 - Line 1 of the commit message should always be a short description of
251   the overall change.  Line 1 does /not/ get a dot at the end.
252 - Line 2 is an empty line
253 - In line 3, the ChangeLog entry should start, in a similar format as
254   in the old ChangeLog files, but without the author information
255   (which is part of the commit anyway).
256 - After the changelog, another empty line should come before any
257   additional information that the committer wishes to provide in order
258   to explain the patch.
259 - If the change is a minor change made by a committer without
260   copyright assignment to the FSF, the commit message should also
261   contain the cookie =TINYCHANGE= (anywhere in the message).  When we
262   later produce the ChangeLog file for Emacs, the change will be
263   marked appropriately.
264
265 Here is an example for such a message
266
267 #+begin_example
268   Capture: Fix the case of using a template file
269       
270   ,* lisp/org-capture.el (org-capture-set-plist): Make sure txt is a string
271   before calling `string-match'.
272   (org-capture-templates): Fix customization type.
273   ,* doc/org.texi (Capture): Document using a file for a template
274       
275   The problem here was that a wrong keyword was given in the
276   customization type.  This let to a string-match against a list value.
277   
278   Modified from a patch proposal by Johan Friis.
279   
280   TINYCHANGE
281 #+end_example
282
283 If you are using /magit.el/ in Emacs, The ChangeLog-like such entries are
284 easily made by pressing =C= in the diff listing.  Another option to make
285 the entries is to use `C-x 4 a' in the changed function.  This will create
286 entries in the ChangeLog file, and you can then cut and paste these to the
287 commit message and remove the indentation.
288
289 * Copyrighted contributors to Org-mode
290
291 #+index: Contributors
292
293 Here is the list of people who have contributed actual code to the
294 Org-mode core.  Note that the manual contains a more extensive list
295 with acknowledgments, including contributed ideas!  The lists below
296 are mostly for house keeping, to help the maintainers keep track of
297 copyright issues.
298
299 ** Current contributors
300   :PROPERTIES:
301   :CUSTOM_ID: contributors_with_fsf_papers
302   :END:
303
304 Here is the list of people who signed the papers with the Free Software
305 Foundation and can now freely submit code to Org files that are included
306 within GNU Emacs:
307
308 1. Adam Elliott
309 2. Andreas Burtzlaff
310 3. Andreas Leha
311 4. Andy Steward
312 5. Anthony Lander
313 6. Baoqiu Cui
314 7. Barry Leonard Gidden
315 8. Bastien Guerry
316 9. Benjamin Andresen
317 10. Bernd Grobauer
318 11. Bernt Hansen
319 12. Brian James Gough
320 13. Carsten Dominik
321 14. Charles Sebold
322 15. Christian Egli
323 16. Christian Moe
324 17. Christopher League
325 18. Christopher Miles Gray
326 19. Christopher Suckling
327 20. Dan Davison
328 21. Daniel M German
329 22. Daniel M. Hackney
330 23. David Maus
331 24. David O'Toole
332 25. Eric S. Fraga
333 26. Eric Schulte
334 27. Erik Iverson
335 28. Giovanni Ridolfi
336 29. Ian Barton
337 30. Ivan Kanis
338 31. James TD Smith
339 32. Jan Böker
340 33. Jason Riedy
341 34. Jeffrey Ryan Horn
342 35. Joel Boehland
343 36. John Wiegley
344 37. Juan Pechiar
345 38. Julian Gehring
346 39. Julien Barnier
347 40. Julien Danjou
348 41. Konrad Hinsen
349 42. Konstantin Antipin
350 43. Lawrence Mitchell
351 44. Lennart Borgman
352 45. Lukasz Stelmach
353 46. Magnus Henoch
354 47. Manuel Giraud
355 48. Martin Pohlack
356 49. Martyn Jago
357 50. Matt Lundin
358 51. Max Mikhanosha
359 52. Michael Brand
360 53. Michael Gauland
361 54. Michael Sperber
362 55. Miguel A. Figueroa-Villanueva
363 56. Mikael Fornius
364 57. Nathan Neff
365 58. Nicolas Goaziou
366 59. Niels Giessen
367 60. Noorul Islam K M
368 61. Paul Sexton
369 62. Peter Jones
370 63. Pieter Praet
371 64. Phil Jackson
372 65. Philip Rooke
373 66. Piotr Zielinski
374 67. Puneeth Chaganti
375 68. Richard Klinda
376 69. Richard Riley
377 70. Ross Patterson
378 71. Russel Adams
379 72. Sacha Chua
380 73. Sebastian Rose
381 74. Sebastien Vauban
382 75. Sergey Litvinov
383 76. Seweryn Kokot
384 77. Stephen Eglen
385 78. Thomas Holst
386 79. Thorsten Jolitz
387 80. Tassilo Horn
388 81. Thomas Baumann
389 82. Thomas S. Dye
390 83. Toby Cubitt
391 84. Tokuya Kameshima
392 85. Tom Breton
393 86. Tomas Hlavaty
394 87. Ulf Stegemann
395 88. Zhang Weize
396
397 ** Processing
398
399 These people have been asked to sign the papers, and they are
400 currently considering it or a request is being processed by the FSF.
401
402 1. Chris Gray
403
404 ** Tiny Changes
405
406 These people have submitted tiny change patches that made it into Org
407 without FSF papers.  When they submit more, we need to get papers
408 eventually.  The limit is a cumulative change of 20 non-repetitive
409 change lines.  Details are given in [[http://www.gnu.org/prep/maintain/maintain.html#Legally-Significant ][this document]].
410
411 1. Robert P. Goldman
412 2. Andy Lutomirski
413 3. Ethan Ligon
414
415 (this list may be incomplete - please help to complete it)
416
417 ** No FSF assignment
418
419 These people cannot or prefer to not sign the FSF copyright papers,
420 and we can only accept patches that do not change the core files (the
421 ones that are also in Emacs).
422
423 Luckily, this list is still empty.
424
425 #+BEGIN: timestamp :string "Last update: " :format "%Y-%m-%d @ %H:%M"
426
427 #+END: