1 #+TITLE: How to contribute to Org?
3 #+EMAIL: mdl AT imapmail DOT org
4 #+OPTIONS: H:3 num:nil toc:t \n:nil ::t |:t ^:nil -: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)
11 #+HTML_LINK_UP: index.html
12 #+HTML_LINK_HOME: https://orgmode.org/worg/
14 # This file is released by its authors and contributors under the GNU
15 # Free Documentation license v1.3 or later, code examples are released
16 # under the GNU General Public License v3 or later.
18 # This file is the default header for new Org files in Worg. Feel free
19 # to tailor it to your needs.
21 * Various ways of contributing to Org
23 :CUSTOM_ID: types-of-contributions
26 Every contribution to Org is very welcome.
28 - You can [[file:donate.org][make a donation]].
30 - You can check the community's *requests for help* on
31 [[https://updates.orgmode.org/#help][updates.orgmode.org]] and subscribe to [[https://updates.orgmode.org/feed/help][this RSS feed]] to track them.
33 - You can *fix bugs* referenced on [[https://updates.orgmode.org/#bugs][updates.orgmode.org]] and subscribe to
34 [[https://updates.orgmode.org/feed/bugs][this RSS feed]].
36 - You can propose [[https://orgmode.org/list/87d015if5g.fsf@gnu.org/][your help as a maintainer for Org Babel files]].
38 - You can try to *reproduce bugs*: subscribe to [[https://lists.gnu.org/mailman/listinfo/emacs-orgmode][Org's mailing list]] and
39 monitor new unreferenced bugs. Try to reproduce them. If you can
40 reproduce a bug, reply to the OP and add =X-Woof-Bug: confirmed= to
41 your mail headers, the bug will then pop up on [[https://updates.orgmode.org/][updates.orgmode.org]].
43 - You can *help other users by replying to their questions* [[file:org-mailing-list.org][on the
44 mailing list]] or on [[file:org-web-social.org][other web places]].
46 - You can *send bug reports*. Before sending a bug report, make sure
47 you have read the [[https://orgmode.org/org.html#Feedback][Feedback]] section of Org's manual or this other
48 great text: [[http://www.chiark.greenend.org.uk/~sgtatham/bugs.html][How to Send Bug Reports Effectively]]
50 - You can *submit patches* to the mailing list. See [[#first-patch][Your first patch]]
51 and [[#patches][Details on how to submit patches]].
53 - You can *contribute to Worg*. Learn what Worg is [[file:worg-about.org][about]] and how to
54 contribute to it [[file:worg-about.org::*How to use git for Worg][How to use git for Worg]].
56 - You can *write add-ons*. The best way is to submit your code to [[file:org-mailing-list.org][the
57 mailing list]] to discuss it with people. If you decide to sign the
58 assignment contract with the FSF, we might include your contribution
59 in the distribution, and then in GNU Emacs.
61 - You can *share ideas and feature requests*. Org is already mature,
62 but new ideas keep popping up. If you want to request a feature,
63 first dig into [[file:org-mailing-list.org][the mailing list]] to find similar proposals. If you
64 cannot find any, subscribe to [[file:org-mailing-list.org][the mailing list]], read it for a while,
65 then make your proposal. Formulate it as detailed as possible, if
66 possible with examples.
68 * As a contributor, what can I expect?
70 :CUSTOM_ID: what-can-I-expect
73 Contributions are discussed on the [[https://orgmode.org/worg/org-mailing-list.html][Org mailing list]].
75 - When you contribute with a bug report :: Expect someone to try
76 reproducing the bug. Please make it easier by providing a minimal
77 reproducible recipe. Check the manual on how to provide [[https://orgmode.org/manual/Feedback.html][feedback]].
78 If no one replies, don't take it personally: it either means that
79 nobody was able to reproduce the bug or that the bug is not that
80 critical for someone else to confirm it.
82 - When you contribute with a patch :: Your patch will be listed on
83 [[https://updates.orgmode.org][updates.orgmode.org]]. If this is your first patch, don't expect the
84 patch to be applied immediately. You can expect someone to review
85 it and to suggest changes, either on the technical or formal aspects
86 of the patch. If nobody seems to care enough to reply, don't take
87 it personally: it means that maintainers are busy and/or that the
88 patch does not seem critical enough.
90 - When you contribute with an idea or a feature request :: The best
91 way to convince maintainers that your idea is worth considering is
92 by detailing your use-case and by proposing a patch for it. Expect
93 people to discuss the idea on the list, but please remember Org is
94 very old now, used by many people with various needs. If nobody
95 replies, don't take it personally.
97 In general, if you want to raise awareness on an email you sent,
98 please wait at least for *one month* before bumping a thread. See [[file:org-mailing-list.org::#i-didnt-receive-an-answer][What
99 to do if you don't receive an answer]].
101 The Org mailing list has *contributor stewards* who will try their best
102 to make sure your contributions get all the attention they deserve.
104 * Your first patch as an occasional contributor
106 :CUSTOM_ID: first-patch
109 You don't need write access to the repository to contribute with
110 patches, just send them to [[file:org-mailing-list.org][the mailing list]]. Here is a checklist to
111 go through before submitting a patch:
113 1. Make your patch against the latest maint or master branch
114 2. Run =~$ make test= to catch broken tests
115 3. Check compilation warning with =~$ make compile=
116 4. If relevant, include or update tests
117 5. If your patch is adding a feature, please update =etc/ORG-NEWS=
118 6. If relevant, don't forget to update =doc/org-manual.org=
119 7. Take extra care of the commit message (see [[#commit-messages][Commit messages and ChangeLog entries]])
120 8. If your change is small enough, include =TINYCHANGE= at the bottom
121 of the commit message.
123 If your patch is against an Org file that is part of Emacs, then your
124 total contribution (all patches you submit) should change /less than 15
125 lines/ (See the [[http://git.savannah.gnu.org/cgit/emacs.git/tree/CONTRIBUTE][CONTRIBUTE file in GNU Emacs]].)
127 If you contribute more, you have to assign the [[#copyright][copyright]] of your
128 contribution to the Free Software Foundation. See [[#devs][Your first commit
129 as an Org committer]].
131 * Your first commit as an Org committer
136 Org regular contributors and maintainers have write access to the [[https://git.savannah.gnu.org/cgit/emacs/org-mode.git/][Git
139 1. Fill in [[https://orgmode.org/request-assign-future.txt][this form]] and wait for the FSF feedback
140 2. Create an account on https://savannah.gnu.org
141 3. Request to join the [[https://savannah.gnu.org/projects/emacs/][Savannah Emacs group]]
143 Once you are granted access to the Emacs group:
145 1. Commit your changes against the code and the documentation
147 3. If the tests pass, push your changes
149 If you are undertaking big changes, please create a dedicated branch
150 locally and make sure you have a clean commit history before merging
151 it into the maint or master branch.
153 To check our Git workflow, please read [[https://orgmode.org/worg/org-maintenance.html][Org maintenance]].
155 * Details on how to submit patches
160 ** Coding conventions
162 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
163 Lisp coding conventions]] described in Emacs manual.
165 ** Sending patch with Git
167 Please use Git to make patches and send them via email -- this is
168 perfectly fine for major and minor changes.
170 When sending a patch (either using =git diff= or =git format-patch=)
171 please *always add a properly formatted Emacs ChangeLog entry*. See
172 [[#commit-messages][this section]] for details on how to create such a ChangeLog.
176 For every patch you send, we suggest to use =git format-patch=.
178 This is easy for small patches and more consequent ones. Sometimes,
179 you might even want to work in several steps and send each commit
180 separately. Here is the suggested workflow:
183 : ~$ git pull # make sure your repo is up to date
184 : ~$ git branch my-changes # create a new branch from master
185 : ~$ git checkout my-changes # switch to this new branch
187 ... make some changes (1) ...
189 : ~$ git commit -a -m "This is change (1)" # Commit your change
191 ... make another change (2) ...
193 : ~$ git commit -a -m "This is change (2)" # Commit your change
194 : ~$ git format-patch master # Creates two patches
196 ... Then two patches for your two commits are ready to be sent to
200 To finally send the patches, you can either add them as attachments to
201 your email, or use [[https://git-scm.com/docs/git-send-email][git send-email]], if it's properly configured.
203 Write useful commit messages: please provide 1) a reason for it in
204 your email and 2) a ChangeLog entry in the commit message (see [[#commit-messages][this
205 section]] on how to format a ChangeLog entry.)
207 ** Sending quick fixes for testing purpose
209 If you want to send a quick fix that needs to be further tested by
210 other people (before you submit a real patch), here is how you can do:
213 This command will make a patch between the staging area (in your
214 computer), and the file you modified:
216 : git diff -p org-whatever.el > org-whatever.el.diff
218 If you already committed your changes to your index (staging area), then
219 you should compare against a particular branch (in this example,
222 : git diff -p origin/master org-whatever.el > org-whatever.el.diff
224 You email the output to the mailing list, adding =[PATCH]= to the
225 subject, and description of what you fixed or changed.
228 Note that small patches sent like this still need to have a ChangeLog
229 entry to be applied. If your patch looks good to you, it's always
230 better to send a patch through =git format-patch=.
232 ** Sharing changes from a public branch
234 When discussing important changes, it is sometimes not so useful to
235 send long and/or numerous patches.
237 In this case, you can maintain your changes on a public branch of a
238 public clone of Org and send a link to the diff between your changes
239 and the latest Org commit that sits in your clone.
241 If the discussion settles and your change is accepted, you can now
242 send it as (a list of) patch(es) to the latest Org version.
244 * Commit messages and ChangeLog entries
246 :CUSTOM_ID: commit-messages
249 We have decided to no longer keep a ChangeLog file to record changes
250 to individual functions.
252 A commit message should be constructed in the following way:
254 - Line 1 of the commit message should always be a short description of
255 the overall change. Line 1 does /not/ get a dot at the end and does
256 not start with a star. Generally, it starts with the filename that
257 has been changed, followed by a colon.
259 - Line 2 is an empty line.
261 - In line 3, the ChangeLog entry should start. A ChangeLog entry
262 looks like [[https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=d49957ef021e256f19092c907d127390d39ec1ed][this]]:
264 : * org-timer.el (org-timer-cancel-timer, org-timer-stop): Enhance
266 : (org-timer-set-timer): Use the number of minutes in the Effort
267 : property as the default timer value. Three prefix arguments will
268 : ignore the Effort value property.
270 - After the changelog, another empty line should come before any
271 additional information that the committer wishes to provide in order
272 to explain the patch.
274 - If the change is a minor change made by a committer without
275 copyright assignment to the FSF, the commit message should also
276 contain the cookie =TINYCHANGE= (anywhere in the message). When we
277 later produce the ChangeLog file for Emacs, the change will be
278 marked appropriately.
280 - Variables and functions names are quoted like `this' (backquote and
283 - Sentences should be separated by two spaces.
285 - Sentences should start with an uppercase letter.
287 - Avoid the passive form: i.e., use "change" instead of "changed".
289 Here is an example for such a message:
292 org-capture.el: Fix the case of using a template file
294 ,* lisp/org-capture.el (org-capture-set-plist): Make sure txt is a
295 string before calling `string-match'.
296 (org-capture-templates): Fix customization type.
298 ,* doc/org.texi (Capture): Document using a file for a template.
300 The problem here was that a wrong keyword was given in the
301 customization type. This let to a string-match against a list value.
303 Modified from a patch proposal by Johan Friis.
308 If you are using [[https://magit.vc/][magit]] in Emacs, the ChangeLog for such entries can be
309 produced by pressing =C= (for ~magit-commit-add-log~) on the diff chunks
310 of a staged file. (If you prefer storing your ChangeLog entries in a
311 file, you can also use =C-x 4 a=
312 (~magit-add-change-log-entry-other-window~) from within magit display of
315 Another option to produce the entries is to use `C-x 4 a' in the
316 changed function or in the diff listing. This will create entries in
317 the ChangeLog file, and you can then cut and paste these to the commit
318 message and remove the indentation.
321 - [[https://www.gnu.org/prep/standards/html_node/Style-of-Change-Logs.html#Style-of-Change-Logs][Standard Emacs change log entry format]]
322 - [[http://git.savannah.gnu.org/cgit/emacs.git/plain/CONTRIBUTE][Contribution guide from Emacs repo]]
324 * Dealing with copyright when contributing to Org mode
326 :CUSTOM_ID: copyright
329 Org is made of many files. Most of them are also distributed as part
330 of GNU Emacs. These files are called the /Org core/, and they are all
331 copyrighted by the [[http://www.fsf.org][Free Software Foundation, Inc]].
333 If you consider contributing to these files, your first need to grant
334 the right to include your works in GNU Emacs to the FSF. For this you
335 need to complete [[https://orgmode.org/request-assign-future.txt][this form]], and send it to [[mailto:assign@gnu.org][assign@gnu.org]].
337 The FSF will send you the assignment contract that both you and the
338 FSF will sign. Please let the Org mode maintainer know when this
341 If you want to learn more about /why/ copyright assignments are
342 collected, read this: [[http://www.gnu.org/licenses/why-assign.html][Why the FSF gets copyright assignments from
345 By submitting patches to =emacs-orgmode@gnu.org= or by pushing changes
346 to Org's core files, you are placing these changes under the same
347 licensing terms as those under which GNU Emacs is published.
350 ;; GNU Emacs is free software: you can redistribute it and/or modify
351 ;; it under the terms of the GNU General Public License as published by
352 ;; the Free Software Foundation, either version 3 of the License, or
353 ;; (at your option) any later version.
356 If at the time you submit or push these changes you do have active
357 copyright assignment papers with the FSF, for future changes to either
358 Org mode or to Emacs, this means that copyright to these changes is
359 automatically transferred to the FSF.
361 The Org mode repository is seen as upstream repository for Emacs,
362 anything contained in it can potentially end up in Emacs. If you do
363 not have signed papers with the FSF, only changes to files in the
364 =contrib/= part of the repository will be accepted, as well as very
365 minor changes (so-called /tiny changes/) to core files. We will ask you
366 to sign FSF papers at the moment we attempt to move a =contrib/= file
367 into the Org core, or into Emacs.
369 * Copyrighted contributors to Org mode
371 :CUSTOM_ID: copyrighted-contributors
374 Here is the list of people who have contributed actual code to the Org
375 mode core. Note that the manual contains a more extensive list with
376 acknowledgments, including contributed ideas! The lists below are
377 mostly for house keeping, to help the maintainers keep track of
380 ** Current contributors
382 :CUSTOM_ID: contributors_with_fsf_papers
385 Here is the list of people who signed the papers with the Free Software
386 Foundation and can now freely submit code to Org files that are included
403 - Andrzej Lichnerowicz
410 - Barry Leonard Gidden
426 - Christopher Miles Gray
427 - Christopher Schmidt
428 - Christopher Suckling
429 - Clément Pit--Claudel
433 - Daniel M.\nbsp{}Hackney
434 - David Arroyo Menéndez
441 - Emmanuel Charpentier
444 - Eric S.\nbsp{}Fraga
451 - Francesco Pizzolante
454 - George Kettleborough
458 - Grégoire Jadi (aka Daimrod)
460 - Henning Dietmar Weiss
486 - Jonathan Leech-Pepin
488 - José L.\nbsp{}Doménech
500 - Kevin Brubeck Unhammer
509 - Leonard Avery Randall
521 - Mark A.\nbsp{}Hershberger
532 - Miguel A.\nbsp{}Figueroa-Villanueva
548 - No Wayman (Nicholas Vollmer)
552 - Pedro Alexandre Marcelino Costa da Silva
561 - Protesilaos Stavrou
565 - Rasmus Pank Roulund
570 - Robert Michael Irelan
586 - Siraphob Phipathananunth
602 - Thomas S.\nbsp{}Dye
606 - Timothy E Chapman (TEC)
607 - Titus von der Malsburg
623 - Yuri D.\nbsp{}Lensky
625 - Zhuo Qingliang (Killy Draw)
629 These people have been asked to sign the papers, and they are
630 currently considering it or a request is being processed by the FSF.
632 - Felipe Lema [2020-02-25 mar.]
633 - Brian Carlson [2016-05-24 Tue]
634 - Mats Kindahl (as of 2013-04-06) for [[http://mid.gmane.org/513BAB7D.1000603@oracle.com][this patch]]
640 These people have submitted tiny change patches that made it into Org
641 without FSF papers. When they submit more, we need to get papers
642 eventually. The limit is a cumulative change of 20 non-repetitive
643 change lines. Details are given in [[http://www.gnu.org/prep/maintain/maintain.html#Legally-Significant ][this document]].
645 - Aaron L.\nbsp{}Zeng
647 - Abhishek Chandratre
653 - Alexandru-Sergiu Marton
663 - Arne Babenhauserheide
676 - Christian Schwarzgruber
683 - Davide Peressoni (DPDmancul)
698 - Francesco Montanari
703 - Greg Tucker-Kellogg
706 - Ivan Vilata i Balaguer
715 - Jean-Marie Gaillourdet
717 - Joaquín Aguirrezabalaga
728 - Konstantin Kliakhandler
731 - Leslie Harlley Watter
765 - Pablo Barraza Cornejo
773 - Richard Y.\nbsp{}Kim (Kim)
776 - Robert P.\nbsp{}Goldman
783 - Saulius Menkevičius
784 - Sebastien Le Maguer
792 - Stefan-W.\nbsp{}Hahn
800 - Thomas Alexander Gerds
812 - Xavier Martinez-Hidalgo
817 - Zane D.\nbsp{}Purvis
820 (This list may be incomplete - please help completing it.)
824 These people cannot or prefer to not sign the FSF copyright papers,
825 and we can only accept patches that do not change the core files (the
826 ones that are also in Emacs).
828 Luckily, this list is still empty.
830 #+BEGIN: timestamp :string "Last update: " :format "%Y-%m-%d @ %H:%M"