Added a few index entries. (Work in progress.)
[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 =http://orgmode.org/w/org-mode.git=
196
197 2. Create a repository that can be publicly accessed, for example on
198    /GitHub/, /repo.or.cz/, or on your own server.
199
200 3. Push your topic branches (and optionally the master branch) to your
201    public repository.
202
203    Define a remote for your public repository you push topics to.
204
205    : git remote add REMOTE URL-GOES-HERE
206
207    Push branches to the remote
208
209    : git push REMOTE BRANCH1 [BRANCH2 BRANCH3 ...]
210
211    e.g.
212
213    : git remote add github ssh://.../     # Done once to define the remote 'github'
214    : git push github my-topic
215
216 4. Do your work on topic-specific branches, using a branch name that
217    relates to what you are working on.
218
219 5. Often do
220
221    : git remote update
222
223    to pull commits from all defined remote repositories, in particular the
224    org-mode master at /orgmode.org/ (or its clone at /repo.or.cz/.)
225
226 6. When you have something workable, publish the git path and branch
227    name on the mailing list, so that people can test it and review
228    your work.
229
230 7. After your topic has been merged to the project master branch you
231    can delete the topic on your local and remote repositories.
232
233    : git branch -d NEWTOPIC
234    : git push REMOTE :NEWTOPIC
235
236 * Commit messages and ChangeLog entries
237
238 #+index: ChangeLog
239 #+index: Commit!Message
240
241 We have decided to no longer keep a ChangeLog file to record changes to
242 individual functions.  In a modern version control system like git,
243 ChangeLog is duplicating information that should be in the commit message,
244 and it is the main cause of merge conflicts.
245
246 Instead, the change log entry should be part of the commit message.  A
247 commit message should be constructed in the following way:
248
249 - Line 1 of the commit message should always be a short description of
250   the overall change.  Line 1 does /not/ get a dot at the end.
251 - Line 2 is an empty line
252 - In line 3, the ChangeLog entry should start, in a similar format as
253   in the old ChangeLog files, but without the author information
254   (which is part of the commit anyway).
255 - After the changelog, another empty line should come before any
256   additional information that the committer wishes to provide in order
257   to explain the patch.
258 - If the change is a minor change made by a committer without
259   copyright assignment to the FSF, the commit message should also
260   contain the cookie =TINYCHANGE= (anywhere in the message).  When we
261   later produce the ChangeLog file for Emacs, the change will be
262   marked appropriately.
263
264 Here is an example for such a message
265
266 #+begin_example
267   Capture: Fix the case of using a template file
268       
269   ,* lisp/org-capture.el (org-capture-set-plist): Make sure txt is a string
270   before calling `string-match'.
271   (org-capture-templates): Fix customization type.
272   ,* doc/org.texi (Capture): Document using a file for a template
273       
274   The problem here was that a wrong keyword was given in the
275   customization type.  This let to a string-match against a list value.
276   
277   Modified from a patch proposal by Johan Friis.
278   
279   TINYCHANGE
280 #+end_example
281
282 If you are using /magit.el/ in Emacs, The ChangeLog-like such entries are
283 easily made by pressing =C= in the diff listing.  Another option to make
284 the entries is to use `C-x 4 a' in the changed function.  This will create
285 entries in the ChangeLog file, and you can then cut and paste these to the
286 commit message and remove the indentation.
287
288 * Copyrighted contributors to Org-mode
289
290 #+index: Contributors
291
292 Here is the list of people who have contributed actual code to the
293 Org-mode core.  Note that the manual contains a more extensive list
294 with acknowledgments, including contributed ideas!  The lists below
295 are mostly for house keeping, to help the maintainers keep track of
296 copyright issues.
297
298 ** Current contributors
299   :PROPERTIES:
300   :CUSTOM_ID: contributors_with_fsf_papers
301   :END:
302
303 Here is the list of people who signed the papers with the Free Software
304 Foundation and can now freely submit code to Org files that are included
305 within GNU Emacs:
306
307 1. Adam Elliott
308 2. Andreas Burtzlaff
309 3. Andreas Leha
310 4. Andy Steward
311 5. Anthony Lander
312 6. Baoqiu Cui
313 7. Barry Leonard Gidden
314 8. Bastien Guerry
315 9. Benjamin Andresen
316 10. Bernd Grobauer
317 11. Bernt Hansen
318 12. Brian James Gough
319 13. Carsten Dominik
320 14. Charles Sebold
321 15. Christian Egli
322 16. Christian Moe
323 17. Christopher League
324 18. Christopher Miles Gray
325 19. Christopher Suckling
326 20. Dan Davison
327 21. Daniel M German
328 22. Daniel M. Hackney
329 23. David Maus
330 24. David O'Toole
331 25. Eric S. Fraga
332 26. Eric Schulte
333 27. Erik Iverson
334 28. Giovanni Ridolfi
335 29. Ian Barton
336 30. James TD Smith
337 31. Jan Böker
338 32. Jason Riedy
339 33. Jeffrey Ryan Horn
340 34. Joel Boehland
341 35. John Wiegley
342 36. Juan Pechiar
343 37. Julian Gehring
344 38. Julien Barnier
345 39. Julien Danjou
346 40. Konstantin Antipin
347 41. Lawrence Mitchell
348 42. Lennart Borgman
349 43. Lukasz Stelmach
350 44. Magnus Henoch
351 45. Manuel Giraud
352 46. Martin Pohlack
353 47. Martyn Jago
354 48. Matt Lundin
355 49. Max Mikhanosha
356 50. Michael Brand
357 51. Michael Gauland
358 52. Michael Sperber
359 53. Miguel A. Figueroa-Villanueva
360 54. Mikael Fornius
361 55. Nathan Neff
362 56. Nicolas Goaziou
363 57. Niels Giessen
364 58. Noorul Islam K M
365 59. Paul Sexton
366 60. Peter Jones
367 61. Pieter Praet
368 62. Phil Jackson
369 63. Philip Rooke
370 64. Piotr Zielinski
371 65. Puneeth Chaganti
372 66. Richard Klinda
373 67. Richard Riley
374 68. Ross Patterson
375 69. Russel Adams
376 70. Sacha Chua
377 71. Sebastian Rose
378 72. Sebastien Vauban
379 73. Sergey Litvinov
380 74. Seweryn Kokot
381 75. Stephen Eglen
382 76. Thomas Holst
383 77. Thorsten Jolitz
384 78. Tassilo Horn
385 79. Thomas Baumann
386 80. Thomas S. Dye
387 81. Tokuya Kameshima
388 82. Tom Breton
389 83. Tomas Hlavaty
390 84. Ulf Stegemann
391 85. Zhang Weize
392
393 ** Processing
394
395 These people have been asked to sign the papers, and they are
396 currently considering it or a request is being processed by the FSF.
397
398 1. Chris Gray
399
400 ** Tiny Changes
401
402 These people have submitted tiny change patches that made it into Org
403 without FSF papers.  When they submit more, we need to get papers
404 eventually.  The limit is a cumulative change of 20 non-repetitive
405 change lines.  Details are given in [[http://www.gnu.org/prep/maintain/maintain.html#Legally-Significant ][this document]].
406
407 1. Robert P. Goldman
408 2. Andy Lutomirski
409 3. Ethan Ligon
410
411 (this list may be incomplete - please help to complete it)
412
413 ** No FSF assignment
414
415 These people cannot or prefer to not sign the FSF copyright papers,
416 and we can only accept patches that do not change the core files (the
417 ones that are also in Emacs).
418
419 Luckily, this list is still empty.
420
421 #+BEGIN: timestamp :string "Last update: " :format "%Y-%m-%d @ %H:%M"
422
423 #+END: