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 [[*Copyright issues when
58 contributing to Emacs Org mode][assignment contract with the FSF]],
59 we might include your contribution in the distribution, and then in
62 - You can *share ideas and feature requests*. Org is already mature,
63 but new ideas keep popping up. If you want to request a feature,
64 first dig into [[file:org-mailing-list.org][the mailing list]] to find similar proposals. If you
65 cannot find any, subscribe to [[file:org-mailing-list.org][the mailing list]], read it for a while,
66 then make your proposal. Formulate it as detailed as possible, if
67 possible with examples.
69 * As a contributor, what can I expect?
71 :CUSTOM_ID: what-can-I-expect
74 Contributions are discussed on the [[https://orgmode.org/worg/org-mailing-list.html][Org mailing list]].
76 - When you contribute with a bug report :: Expect someone to try
77 reproducing the bug. Please make it easier by providing a minimal
78 reproducible recipe. Check the manual on how to provide [[https://orgmode.org/manual/Feedback.html][feedback]].
79 If no one replies, don't take it personally: it either means that
80 nobody was able to reproduce the bug or that the bug is not that
81 critical for someone else to confirm it.
83 - When you contribute with a patch :: Your patch will be listed on
84 [[https://updates.orgmode.org][updates.orgmode.org]]. If this is your first patch, don't expect the
85 patch to be applied immediately. You can expect someone to review
86 it and to suggest changes, either on the technical or formal aspects
87 of the patch. If nobody seems to care enough to reply, don't take
88 it personally: it means that maintainers are busy and/or that the
89 patch does not seem critical enough.
91 - When you contribute with an idea or a feature request :: The best
92 way to convince maintainers that your idea is worth considering is
93 by detailing your use-case and by proposing a patch for it. Expect
94 people to discuss the idea on the list, but please remember Org is
95 very old now, used by many people with various needs. If nobody
96 replies, don't take it personally.
98 In general, if you want to raise awareness on an email you sent,
99 please wait at least for *one month* before bumping a thread. See [[file:org-mailing-list.org::#i-didnt-receive-an-answer][What
100 to do if you don't receive an answer]].
102 The Org mailing list has *contributor stewards* who will try their best
103 to make sure your contributions get all the attention they deserve.
105 * Your first patch as an occasional contributor
107 :CUSTOM_ID: first-patch
110 You don't need write access to the repository to contribute with
111 patches, just send them to [[file:org-mailing-list.org][the mailing list]]. Here is a checklist to
112 go through before submitting a patch:
114 1. Make your patch against the latest maint or master branch
115 2. Run =~$ make test= to catch broken tests
116 3. Check compilation warning with =~$ make compile=
117 4. If relevant, include or update tests
118 5. If your patch is adding a feature, please update =etc/ORG-NEWS=
119 6. If relevant, don't forget to update =doc/org-manual.org=
120 7. Take extra care of the commit message (see [[#commit-messages][Commit messages and ChangeLog entries]])
121 8. If your change is small enough, include =TINYCHANGE= at the bottom
122 of the commit message.
124 If your patch is against an Org file that is part of Emacs, then your
125 total contribution (all patches you submit) should change /less than 15
126 lines/ (See the [[http://git.savannah.gnu.org/cgit/emacs.git/tree/CONTRIBUTE][CONTRIBUTE file in GNU Emacs]].)
128 If you contribute more, you have to assign the [[#copyright][copyright]] of your
129 contribution to the Free Software Foundation. See [[#devs][Your first commit
130 as an Org committer]].
132 * Your first commit as an Org committer
137 Org regular contributors and maintainers have write access to the Git
140 1. Fill in [[https://orgmode.org/request-assign-future.txt][this form]] and wait for the FSF feedback
141 2. Send [[mailto:bzgATgnuDOTorg][Bastien]] the username you want for https://code.orgmode.org
142 3. Add your public key to your account, once its creation is confirmed
143 4. Clone =org-mode.git=: =~$ git clone git@code.orgmode.org:bzg/org-mode.git=
144 5. Commit your changes against the code and the documentation
146 7. If the tests pass, push your changes
148 If you are undertaking big changes, please create a dedicated branch
149 locally and make sure you have a clean commit history before merging
150 it into the maint or master branch.
152 To check our Git workflow, please read [[https://orgmode.org/worg/org-maintenance.html][Org maintenance]].
154 * Details on how to submit patches
159 ** Coding conventions
161 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
162 Lisp coding conventions]] described in Emacs manual.
164 ** Sending patch with Git
166 Please use Git to make patches and send them via email -- this is
167 perfectly fine for major and minor changes.
169 When sending a patch (either using =git diff= or =git format-patch=)
170 please *always add a properly formatted Emacs ChangeLog entry*. See
171 [[#commit-messages][this section]] for details on how to create such a ChangeLog.
175 For every patch you send, we suggest to use =git format-patch=.
177 This is easy for small patches and more consequent ones. Sometimes,
178 you might even want to work in several steps and send each commit
179 separately. Here is the suggested workflow:
182 : ~$ git pull # make sure your repo is up to date
183 : ~$ git branch my-changes # create a new branch from master
184 : ~$ git checkout my-changes # switch to this new branch
186 ... make some changes (1) ...
188 : ~$ git commit -a -m "This is change (1)" # Commit your change
190 ... make another change (2) ...
192 : ~$ git commit -a -m "This is change (2)" # Commit your change
193 : ~$ git format-patch master # Creates two patches
195 ... Then two patches for your two commits are ready to be sent to
199 To finally send the patches, you can either add them as attachments to
200 your email, or use [[https://git-scm.com/docs/git-send-email][git send-email]], if it's properly configured.
202 Write useful commit messages: please provide 1) a reason for it in
203 your email and 2) a ChangeLog entry in the commit message (see [[#commit-messages][this
204 section]] on how to format a ChangeLog entry.)
206 ** Sending quick fixes for testing purpose
208 If you want to send a quick fix that needs to be further tested by
209 other people (before you submit a real patch), here is how you can do:
212 This command will make a patch between the staging area (in your
213 computer), and the file you modified:
215 : git diff -p org-whatever.el > org-whatever.el.diff
217 If you already committed your changes to your index (staging area), then
218 you should compare against a particular branch (in this example,
221 : git diff -p origin/master org-whatever.el > org-whatever.el.diff
223 You email the output to the mailing list, adding =[PATCH]= to the
224 subject, and description of what you fixed or changed.
227 Note that small patches sent like this still need to have a ChangeLog
228 entry to be applied. If your patch looks good to you, it's always
229 better to send a patch through =git format-patch=.
231 ** Sharing changes from a public branch
233 When discussing important changes, it is sometimes not so useful to
234 send long and/or numerous patches.
236 In this case, you can maintain your changes on a public branch of a
237 public clone of Org and send a link to the diff between your changes
238 and the latest Org commit that sits in your clone.
240 If the discussion settles and your change is accepted, you can now
241 send it as (a list of) patch(es) to the latest Org version.
243 * Commit messages and ChangeLog entries
245 :CUSTOM_ID: commit-messages
248 We have decided to no longer keep a ChangeLog file to record changes
249 to individual functions.
251 A commit message should be constructed in the following way:
253 - Line 1 of the commit message should always be a short description of
254 the overall change. Line 1 does /not/ get a dot at the end and does
255 not start with a star. Generally, it starts with the filename that
256 has been changed, followed by a colon.
258 - Line 2 is an empty line.
260 - In line 3, the ChangeLog entry should start. A ChangeLog entry
261 looks like [[https://code.orgmode.org/bzg/org-mode/commit/d49957ef021e256f19092c907d127390d39ec1ed][this]]:
263 : * org-timer.el (org-timer-cancel-timer, org-timer-stop): Enhance
265 : (org-timer-set-timer): Use the number of minutes in the Effort
266 : property as the default timer value. Three prefix arguments will
267 : ignore the Effort value property.
269 - After the changelog, another empty line should come before any
270 additional information that the committer wishes to provide in order
271 to explain the patch.
273 - If the change is a minor change made by a committer without
274 copyright assignment to the FSF, the commit message should also
275 contain the cookie =TINYCHANGE= (anywhere in the message). When we
276 later produce the ChangeLog file for Emacs, the change will be
277 marked appropriately.
279 - Variables and functions names are quoted like `this' (backquote and
282 - Sentences should be separated by two spaces.
284 - Sentences should start with an uppercase letter.
286 - Avoid the passive form: i.e., use "change" instead of "changed".
288 Here is an example for such a message:
291 org-capture.el: Fix the case of using a template file
293 ,* lisp/org-capture.el (org-capture-set-plist): Make sure txt is a
294 string before calling `string-match'.
295 (org-capture-templates): Fix customization type.
297 ,* doc/org.texi (Capture): Document using a file for a template.
299 The problem here was that a wrong keyword was given in the
300 customization type. This let to a string-match against a list value.
302 Modified from a patch proposal by Johan Friis.
307 If you are using [[https://magit.vc/][magit]] in Emacs, the ChangeLog for such entries can be
308 produced by pressing =C= (for ~magit-commit-add-log~) on the diff chunks
309 of a staged file. (If you prefer storing your ChangeLog entries in a
310 file, you can also use =C-x 4 a=
311 (~magit-add-change-log-entry-other-window~) from within magit display of
314 Another option to produce the entries is to use `C-x 4 a' in the
315 changed function or in the diff listing. This will create entries in
316 the ChangeLog file, and you can then cut and paste these to the commit
317 message and remove the indentation.
320 - [[https://www.gnu.org/prep/standards/html_node/Style-of-Change-Logs.html#Style-of-Change-Logs][Standard Emacs change log entry format]]
321 - [[http://git.savannah.gnu.org/cgit/emacs.git/plain/CONTRIBUTE][Contribution guide from Emacs repo]]
323 * Dealing with copyright when contributing to Org mode
325 :CUSTOM_ID: copyright
328 Org is made of many files. Most of them are also distributed as part
329 of GNU Emacs. These files are called the /Org core/, and they are all
330 copyrighted by the [[http://www.fsf.org][Free Software Foundation, Inc]].
332 If you consider contributing to these files, your first need to grant
333 the right to include your works in GNU Emacs to the FSF. For this you
334 need to complete [[https://orgmode.org/request-assign-future.txt][this form]], and send it to [[mailto:assign@gnu.org][assign@gnu.org]].
336 The FSF will send you the assignment contract that both you and the
337 FSF will sign. Please let the Org mode maintainer know when this
340 If you want to learn more about /why/ copyright assignments are
341 collected, read this: [[http://www.gnu.org/licenses/why-assign.html][Why the FSF gets copyright assignments from
344 By submitting patches to =emacs-orgmode@gnu.org= or by pushing changes
345 to Org's core files, you are placing these changes under the same
346 licensing terms as those under which GNU Emacs is published.
349 ;; GNU Emacs is free software: you can redistribute it and/or modify
350 ;; it under the terms of the GNU General Public License as published by
351 ;; the Free Software Foundation, either version 3 of the License, or
352 ;; (at your option) any later version.
355 If at the time you submit or push these changes you do have active
356 copyright assignment papers with the FSF, for future changes to either
357 Org mode or to Emacs, this means that copyright to these changes is
358 automatically transferred to the FSF.
360 The Org mode repository is seen as upstream repository for Emacs,
361 anything contained in it can potentially end up in Emacs. If you do
362 not have signed papers with the FSF, only changes to files in the
363 =contrib/= part of the repository will be accepted, as well as very
364 minor changes (so-called /tiny changes/) to core files. We will ask you
365 to sign FSF papers at the moment we attempt to move a =contrib/= file
366 into the Org core, or into Emacs.
368 * Copyrighted contributors to Org mode
370 :CUSTOM_ID: copyrighted-contributors
373 Here is the list of people who have contributed actual code to the Org
374 mode core. Note that the manual contains a more extensive list with
375 acknowledgments, including contributed ideas! The lists below are
376 mostly for house keeping, to help the maintainers keep track of
379 ** Current contributors
381 :CUSTOM_ID: contributors_with_fsf_papers
384 Here is the list of people who signed the papers with the Free Software
385 Foundation and can now freely submit code to Org files that are included
402 - Andrzej Lichnerowicz
409 - Barry Leonard Gidden
425 - Christopher Miles Gray
426 - Christopher Schmidt
427 - Christopher Suckling
428 - Clément Pit--Claudel
432 - Daniel M.\nbsp{}Hackney
433 - David Arroyo Menéndez
440 - Emmanuel Charpentier
443 - Eric S.\nbsp{}Fraga
450 - Francesco Pizzolante
453 - George Kettleborough
457 - Grégoire Jadi (aka Daimrod)
459 - Henning Dietmar Weiss
485 - Jonathan Leech-Pepin
487 - José L.\nbsp{}Doménech
499 - Kevin Brubeck Unhammer
508 - Leonard Avery Randall
520 - Mark A.\nbsp{}Hershberger
531 - Miguel A.\nbsp{}Figueroa-Villanueva
547 - No Wayman (Nicholas Vollmer)
551 - Pedro Alexandre Marcelino Costa da Silva
560 - Protesilaos Stavrou
564 - Rasmus Pank Roulund
569 - Robert Michael Irelan
585 - Siraphob Phipathananunth
601 - Thomas S.\nbsp{}Dye
605 - Timothy E Chapman (TEC)
606 - Titus von der Malsburg
622 - Yuri D.\nbsp{}Lensky
624 - Zhuo Qingliang (Killy Draw)
628 These people have been asked to sign the papers, and they are
629 currently considering it or a request is being processed by the FSF.
631 - Felipe Lema [2020-02-25 mar.]
632 - Brian Carlson [2016-05-24 Tue]
633 - Mats Kindahl (as of 2013-04-06) for [[http://mid.gmane.org/513BAB7D.1000603@oracle.com][this patch]]
639 These people have submitted tiny change patches that made it into Org
640 without FSF papers. When they submit more, we need to get papers
641 eventually. The limit is a cumulative change of 20 non-repetitive
642 change lines. Details are given in [[http://www.gnu.org/prep/maintain/maintain.html#Legally-Significant ][this document]].
644 - Aaron L.\nbsp{}Zeng
646 - Abhishek Chandratre
652 - Alexandru-Sergiu Marton
662 - Arne Babenhauserheide
675 - Christian Schwarzgruber
682 - Davide Peressoni (DPDmancul)
697 - Francesco Montanari
702 - Greg Tucker-Kellogg
705 - Ivan Vilata i Balaguer
714 - Jean-Marie Gaillourdet
716 - Joaquín Aguirrezabalaga
727 - Konstantin Kliakhandler
730 - Leslie Harlley Watter
764 - Pablo Barraza Cornejo
772 - Richard Y.\nbsp{}Kim (Kim)
775 - Robert P.\nbsp{}Goldman
782 - Saulius Menkevičius
783 - Sebastien Le Maguer
791 - Stefan-W.\nbsp{}Hahn
799 - Thomas Alexander Gerds
811 - Xavier Martinez-Hidalgo
816 - Zane D.\nbsp{}Purvis
819 (This list may be incomplete - please help completing it.)
823 These people cannot or prefer to not sign the FSF copyright papers,
824 and we can only accept patches that do not change the core files (the
825 ones that are also in Emacs).
827 Luckily, this list is still empty.
829 #+BEGIN: timestamp :string "Last update: " :format "%Y-%m-%d @ %H:%M"