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 try to *reproduce bugs*: subscribe to [[https://lists.gnu.org/mailman/listinfo/emacs-orgmode][Org's mailing list]] and
37 monitor new unreferenced bugs. Try to reproduce them. If you can
38 reproduce a bug, reply to the OP and add =X-Woof-Bug: confirmed= to
39 your mail headers, the bug will then pop up on [[https://updates.orgmode.org/][updates.orgmode.org]].
41 - You can *help other users by replying to their questions* [[file:org-mailing-list.org][on the
42 mailing list]] or on [[file:org-web-social.org][other web places]].
44 - You can *send bug reports*. Before sending a bug report, make sure
45 you have read the [[https://orgmode.org/org.html#Feedback][Feedback]] section of Org's manual or this other
46 great text: [[http://www.chiark.greenend.org.uk/~sgtatham/bugs.html][How to Send Bug Reports Effectively]]
48 - You can *submit patches* to the mailing list. See [[#first-patch][Your first patch]]
49 and [[#patches][Details on how to submit patches]].
51 - You can *contribute to Worg*. Learn what Worg is [[file:worg-about.org][about]] and how to
52 contribute to it [[file:worg-git.org][through git]].
54 - You can *write add-ons*. The best way is to submit your code to [[file:org-mailing-list.org][the
55 mailing list]] to discuss it with people. If you decide to sign the [[*Copyright issues when
56 contributing to Emacs Org mode][assignment contract with the FSF]],
57 we might include your contribution in the distribution, and then in
60 - You can *share ideas and feature requests*. Org is already mature,
61 but new ideas keep popping up. If you want to request a feature,
62 first dig into [[file:org-mailing-list.org][the mailing list]] to find similar proposals. If you
63 cannot find any, subscribe to [[file:org-mailing-list.org][the mailing list]], read it for a while,
64 then make your proposal. Formulate it as detailed as possible, if
65 possible with examples.
67 * As a contributor, what can I expect?
69 :CUSTOM_ID: what-can-I-expect
72 Contributions are discussed on the [[https://orgmode.org/worg/org-mailing-list.html][Org mailing list]].
74 - When you contribute with a bug report :: Expect someone to try
75 reproducing the bug. Please make it easier by providing a minimal
76 reproducible recipe. Check the manual on how to provide [[https://orgmode.org/manual/Feedback.html][feedback]].
77 If no one replies, don't take it personally: it either means that
78 nobody was able to reproduce the bug or that the bug is not that
79 critical for someone else to confirm it.
81 - When you contribute with a patch :: Your patch will be listed on
82 [[https://updates.orgmode.org][updates.orgmode.org]]. If this is your first patch, don't expect the
83 patch to be applied immediately. You can expect someone to review
84 it and to suggest changes, either on the technical or formal aspects
85 of the patch. If nobody seems to care enough to reply, don't take
86 it personally: it means that maintainers are busy and/or that the
87 patch does not seem critical enough.
89 - When you contribute with an idea or a feature request :: The best
90 way to convince maintainers that your idea is worth considering is
91 by detailing your use-case and by proposing a patch for it. Expect
92 people to discuss the idea on the list, but please remember Org is
93 very old now, used by many people with various needs. If nobody
94 replies, don't take it personally.
96 In general, if you want to raise awareness on an email you sent,
97 please wait at least for *one month* before bumping a thread. See [[file:org-mailing-list.org::#i-didnt-receive-an-answer][What
98 to do if you don't receive an answer]].
100 The Org mailing list has *contributor stewards* who will try their best
101 to make sure your contributions get all the attention they deserve.
103 * Your first patch as an occasional contributor
105 :CUSTOM_ID: first-patch
108 You don't need write access to the repository to contribute with
109 patches, just send them to [[file:org-mailing-list.org][the mailing list]]. Here is a checklist to
110 go through before submitting a patch:
112 1. Make your patch against the latest maint or master branch
113 2. Run =~$ make test= to catch broken tests
114 3. Check compilation warning with =~$ make compile=
115 4. If relevant, include or update tests
116 5. If your patch is adding a feature, please update =etc/ORG-NEWS=
117 6. If relevant, don't forget to update =doc/org-manual.org=
118 7. Take extra care of the commit message (see [[#commit-messages][Commit messages and ChangeLog entries]])
119 8. If your change is small enough, include =TINYCHANGE= at the bottom
120 of the commit message.
122 If your patch is against an Org file that is part of Emacs, then your
123 total contribution (all patches you submit) should change /less than 15
124 lines/ (See the [[http://git.savannah.gnu.org/cgit/emacs.git/tree/CONTRIBUTE][CONTRIBUTE file in GNU Emacs]].)
126 If you contribute more, you have to assign the [[#copyright][copyright]] of your
127 contribution to the Free Software Foundation. See [[#devs][Your first commit
128 as an Org committer]].
130 * Your first commit as an Org committer
135 Org regular contributors and maintainers have write access to the Git
138 1. Fill in [[https://orgmode.org/request-assign-future.txt][this form]] and wait for the FSF feedback
139 2. Send [[mailto:bzgATgnuDOTorg][Bastien]] the username you want for https://code.orgmode.org
140 3. Add your public key to your account, once its creation is confirmed
141 4. Clone =org-mode.git=: =~$ git clone git@code.orgmode.org:bzg/org-mode.git=
142 5. Commit your changes against the code and the documentation
144 7. If the tests pass, push your changes
146 If you are undertaking big changes, please create a dedicated branch
147 locally and make sure you have a clean commit history before merging
148 it into the maint or master branch.
150 To check our Git workflow, please read [[https://orgmode.org/worg/org-maintenance.html][Org maintenance]].
152 * Details on how to submit patches
157 ** Coding conventions
159 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
160 Lisp coding conventions]] described in Emacs manual.
162 ** Sending patch with Git
164 Please use Git to make patches and send them via email -- this is
165 perfectly fine for major and minor changes.
167 When sending a patch (either using =git diff= or =git format-patch=)
168 please *always add a properly formatted Emacs ChangeLog entry*. See
169 [[#commit-messages][this section]] for details on how to create such a ChangeLog.
173 For every patch you send, we suggest to use =git format-patch=.
175 This is easy for small patches and more consequent ones. Sometimes,
176 you might even want to work in several steps and send each commit
177 separately. Here is the suggested workflow:
180 : ~$ git pull # make sure your repo is up to date
181 : ~$ git branch my-changes # create a new branch from master
182 : ~$ git checkout my-changes # switch to this new branch
184 ... make some changes (1) ...
186 : ~$ git commit -a -m "This is change (1)" # Commit your change
188 ... make another change (2) ...
190 : ~$ git commit -a -m "This is change (2)" # Commit your change
191 : ~$ git format-patch master # Creates two patches
193 ... Then two patches for your two commits are ready to be sent to
197 To finally send the patches, you can either add them as attachments to
198 your email, or use [[https://git-scm.com/docs/git-send-email][git send-email]], if it's properly configured.
200 Write useful commit messages: please provide 1) a reason for it in
201 your email and 2) a ChangeLog entry in the commit message (see [[#commit-messages][this
202 section]] on how to format a ChangeLog entry.)
204 ** Sending quick fixes for testing purpose
206 If you want to send a quick fix that needs to be further tested by
207 other people (before you submit a real patch), here is how you can do:
210 This command will make a patch between the staging area (in your
211 computer), and the file you modified:
213 : git diff -p org-whatever.el > org-whatever.el.diff
215 If you already committed your changes to your index (staging area), then
216 you should compare against a particular branch (in this example,
219 : git diff -p origin/master org-whatever.el > org-whatever.el.diff
221 You email the output to the mailing list, adding =[PATCH]= to the
222 subject, and description of what you fixed or changed.
225 Note that small patches sent like this still need to have a ChangeLog
226 entry to be applied. If your patch looks good to you, it's always
227 better to send a patch through =git format-patch=.
229 ** Sharing changes from a public branch
231 When discussing important changes, it is sometimes not so useful to
232 send long and/or numerous patches.
234 In this case, you can maintain your changes on a public branch of a
235 public clone of Org and send a link to the diff between your changes
236 and the latest Org commit that sits in your clone.
238 If the discussion settles and your change is accepted, you can now
239 send it as (a list of) patch(es) to the latest Org version.
241 * Commit messages and ChangeLog entries
243 :CUSTOM_ID: commit-messages
246 We have decided to no longer keep a ChangeLog file to record changes
247 to individual functions.
249 A commit message should be constructed in the following way:
251 - Line 1 of the commit message should always be a short description of
252 the overall change. Line 1 does /not/ get a dot at the end and does
253 not start with a star. Generally, it starts with the filename that
254 has been changed, followed by a colon.
256 - Line 2 is an empty line.
258 - In line 3, the ChangeLog entry should start. A ChangeLog entry
259 looks like [[https://code.orgmode.org/bzg/org-mode/commit/d49957ef021e256f19092c907d127390d39ec1ed][this]]:
261 : * org-timer.el (org-timer-cancel-timer, org-timer-stop): Enhance
263 : (org-timer-set-timer): Use the number of minutes in the Effort
264 : property as the default timer value. Three prefix arguments will
265 : ignore the Effort value property.
267 - After the changelog, another empty line should come before any
268 additional information that the committer wishes to provide in order
269 to explain the patch.
271 - If the change is a minor change made by a committer without
272 copyright assignment to the FSF, the commit message should also
273 contain the cookie =TINYCHANGE= (anywhere in the message). When we
274 later produce the ChangeLog file for Emacs, the change will be
275 marked appropriately.
277 - Variables and functions names are quoted like `this' (backquote and
280 - Sentences should be separated by two spaces.
282 - Sentences should start with an uppercase letter.
284 - Avoid the passive form: i.e., use "change" instead of "changed".
286 Here is an example for such a message:
289 org-capture.el: Fix the case of using a template file
291 ,* lisp/org-capture.el (org-capture-set-plist): Make sure txt is a
292 string before calling `string-match'.
293 (org-capture-templates): Fix customization type.
295 ,* doc/org.texi (Capture): Document using a file for a template.
297 The problem here was that a wrong keyword was given in the
298 customization type. This let to a string-match against a list value.
300 Modified from a patch proposal by Johan Friis.
305 If you are using [[https://magit.vc/][magit]] in Emacs, the ChangeLog for such entries can be
306 produced by pressing =C= (for ~magit-commit-add-log~) on the diff chunks
307 of a staged file. (If you prefer storing your ChangeLog entries in a
308 file, you can also use =C-x 4 a=
309 (~magit-add-change-log-entry-other-window~) from within magit display of
312 Another option to produce the entries is to use `C-x 4 a' in the
313 changed function or in the diff listing. This will create entries in
314 the ChangeLog file, and you can then cut and paste these to the commit
315 message and remove the indentation.
318 - [[https://www.gnu.org/prep/standards/html_node/Style-of-Change-Logs.html#Style-of-Change-Logs][Standard Emacs change log entry format]]
319 - [[http://git.savannah.gnu.org/cgit/emacs.git/plain/CONTRIBUTE][Contribution guide from Emacs repo]]
321 * Dealing with copyright when contributing to Org mode
323 :CUSTOM_ID: copyright
326 Org is made of many files. Most of them are also distributed as part
327 of GNU Emacs. These files are called the /Org core/, and they are all
328 copyrighted by the [[http://www.fsf.org][Free Software Foundation, Inc]].
330 If you consider contributing to these files, your first need to grant
331 the right to include your works in GNU Emacs to the FSF. For this you
332 need to complete [[https://orgmode.org/request-assign-future.txt][this form]], and send it to [[mailto:assign@gnu.org][assign@gnu.org]].
334 The FSF will send you the assignment contract that both you and the
335 FSF will sign. Please let the Org mode maintainer know when this
338 If you want to learn more about /why/ copyright assignments are
339 collected, read this: [[http://www.gnu.org/licenses/why-assign.html][Why the FSF gets copyright assignments from
342 By submitting patches to =emacs-orgmode@gnu.org= or by pushing changes
343 to Org's core files, you are placing these changes under the same
344 licensing terms as those under which GNU Emacs is published.
347 ;; GNU Emacs is free software: you can redistribute it and/or modify
348 ;; it under the terms of the GNU General Public License as published by
349 ;; the Free Software Foundation, either version 3 of the License, or
350 ;; (at your option) any later version.
353 If at the time you submit or push these changes you do have active
354 copyright assignment papers with the FSF, for future changes to either
355 Org mode or to Emacs, this means that copyright to these changes is
356 automatically transferred to the FSF.
358 The Org mode repository is seen as upstream repository for Emacs,
359 anything contained in it can potentially end up in Emacs. If you do
360 not have signed papers with the FSF, only changes to files in the
361 =contrib/= part of the repository will be accepted, as well as very
362 minor changes (so-called /tiny changes/) to core files. We will ask you
363 to sign FSF papers at the moment we attempt to move a =contrib/= file
364 into the Org core, or into Emacs.
366 * Copyrighted contributors to Org mode
368 :CUSTOM_ID: copyrighted-contributors
371 Here is the list of people who have contributed actual code to the Org
372 mode core. Note that the manual contains a more extensive list with
373 acknowledgments, including contributed ideas! The lists below are
374 mostly for house keeping, to help the maintainers keep track of
377 ** Current contributors
379 :CUSTOM_ID: contributors_with_fsf_papers
382 Here is the list of people who signed the papers with the Free Software
383 Foundation and can now freely submit code to Org files that are included
400 - Andrzej Lichnerowicz
407 - Barry Leonard Gidden
423 - Christopher Miles Gray
424 - Christopher Schmidt
425 - Christopher Suckling
426 - Clément Pit--Claudel
430 - Daniel M.\nbsp{}Hackney
431 - David Arroyo Menéndez
438 - Emmanuel Charpentier
441 - Eric S.\nbsp{}Fraga
448 - Francesco Pizzolante
451 - George Kettleborough
455 - Grégoire Jadi (aka Daimrod)
457 - Henning Dietmar Weiss
483 - Jonathan Leech-Pepin
485 - José L.\nbsp{}Doménech
497 - Kevin Brubeck Unhammer
506 - Leonard Avery Randall
518 - Mark A.\nbsp{}Hershberger
529 - Miguel A.\nbsp{}Figueroa-Villanueva
545 - No Wayman (Nicholas Vollmer)
549 - Pedro Alexandre Marcelino Costa da Silva
558 - Protesilaos Stavrou
562 - Rasmus Pank Roulund
567 - Robert Michael Irelan
583 - Siraphob Phipathananunth
599 - Thomas S.\nbsp{}Dye
603 - Timothy E Chapman (TEC)
604 - Titus von der Malsburg
619 - Yuri D.\nbsp{}Lensky
621 - Zhuo Qingliang (Killy Draw)
625 These people have been asked to sign the papers, and they are
626 currently considering it or a request is being processed by the FSF.
628 - Felipe Lema [2020-02-25 mar.]
629 - Brian Carlson [2016-05-24 Tue]
630 - Mats Kindahl (as of 2013-04-06) for [[http://mid.gmane.org/513BAB7D.1000603@oracle.com][this patch]]
636 These people have submitted tiny change patches that made it into Org
637 without FSF papers. When they submit more, we need to get papers
638 eventually. The limit is a cumulative change of 20 non-repetitive
639 change lines. Details are given in [[http://www.gnu.org/prep/maintain/maintain.html#Legally-Significant ][this document]].
641 - Aaron L.\nbsp{}Zeng
643 - Abhishek Chandratre
649 - Alexandru-Sergiu Marton
659 - Arne Babenhauserheide
672 - Christian Schwarzgruber
693 - Francesco Montanari
698 - Greg Tucker-Kellogg
701 - Ivan Vilata i Balaguer
710 - Jean-Marie Gaillourdet
712 - Joaquín Aguirrezabalaga
723 - Konstantin Kliakhandler
726 - Leslie Harlley Watter
758 - Pablo Barraza Cornejo
766 - Richard Y.\nbsp{}Kim (Kim)
769 - Robert P.\nbsp{}Goldman
774 - Saulius Menkevičius
775 - Sebastien Le Maguer
783 - Stefan-W.\nbsp{}Hahn
791 - Thomas Alexander Gerds
803 - Xavier Martinez-Hidalgo
808 - Zane D.\nbsp{}Purvis
811 (This list may be incomplete - please help completing it.)
815 These people cannot or prefer to not sign the FSF copyright papers,
816 and we can only accept patches that do not change the core files (the
817 ones that are also in Emacs).
819 Luckily, this list is still empty.
821 #+BEGIN: timestamp :string "Last update: " :format "%Y-%m-%d @ %H:%M"