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)
12 # This file is the default header for new Org files in Worg. Feel free
13 # to tailor it to your needs.
15 [[file:index.org][{Back to Worg's index}]]
17 * Types of contributions
19 :CUSTOM_ID: types-of-contributions
22 Every contribution to Org is very welcome. Here is a list of areas
23 where your contribution will be useful:
25 - bug reports :: Before sending a bug report, make sure you have read
26 this section of Org's manual: [[https://orgmode.org/org.html#Feedback][Feedback]] You can also read this great
27 text: "[[http://www.chiark.greenend.org.uk/~sgtatham/bugs.html][How to Send Bug Reports Effectively]]"
29 - patches :: You can submit patches to the mailing list. See the
30 [[For Org contributors: preferred way of submitting
31 patches][Preferred way of submitting patches]] section for details. You can run
32 =make test= to check that your patch does not introduce new bugs.
34 If your patch is against a file that is part of Emacs, then your
35 total contribution (all patches you submit) should change /less than
36 15 lines/ (See the [[http://git.savannah.gnu.org/cgit/emacs.git/tree/CONTRIBUTE][CONTRIBUTE file in GNU Emacs]].) If you contribute
37 more, you have to assign the copyright of your contribution to the
38 Free Software Foundation (see below).
40 - material to the Worg website :: This website is made of Org files
41 that you can contribute to. Learn what Worg is [[file:worg-about.org][about]] and how to
42 contribute to it [[file:worg-git.org][through git]].
44 - feature requests :: Org is already mature, but new ideas keep
45 popping up. If you want to request a feature, first dig into the
46 mailing list to find similar proposals. If you cannot find any,
47 subscribe to [[file:org-mailing-list.org][the mailing list]], read it for a while, then make your
48 proposal. Formulate it as detailed as possible, if possible with
51 - Org add-ons :: there are many Org add-ons.
52 - The best way is to submit your code to [[file:org-mailing-list.org][the mailing list]] to discuss
54 - If it is useful, you might consider contributing it to the
55 =lisp/contrib/= directory in the git repository. It will be
56 reviewed, and if it passes, it will be included. The
57 =lisp/contrib/= directory is somehow relaxed: it is not distributed
58 with Emacs, and does not require a formal copyright assignment.
59 - If you decide to sign the [[*Copyright issues when contributing to Emacs Org mode][assignment contract with the FSF]], we
60 might include your contribution in the distribution, and then in
63 * Copyright issues when contributing to Emacs Org mode
65 :CUSTOM_ID: copyright-issues
68 Org is made of many files. Most of them are also distributed as part
69 of GNU Emacs. These files are called the /Org core/, and they are all
70 copyrighted by the [[http://www.fsf.org][Free Software Foundation, Inc]].
72 If you consider contributing to these files, your first need to grant
73 the right to include your works in GNU Emacs to the FSF. For this you
74 need to complete [[https://orgmode.org/request-assign-future.txt][this form]], and send it to [[mailto:assign@gnu.org][assign@gnu.org]].
76 The FSF will send you the assignment contract that both you and the
77 FSF will sign. Please let the Org mode maintainer know when this
80 If you want to learn more about /why/ copyright assignments are
81 collected, read this: [[http://www.gnu.org/licenses/why-assign.html][Why the FSF gets copyright assignments from
84 By submitting patches to =emacs-orgmode@gnu.org= or by pushing changes
85 to Org's core files, you are placing these changes under the same
86 licensing terms as those under which GNU Emacs is published.
89 ;; GNU Emacs is free software: you can redistribute it and/or modify
90 ;; it under the terms of the GNU General Public License as published by
91 ;; the Free Software Foundation, either version 3 of the License, or
92 ;; (at your option) any later version.
95 If at the time you submit or push these changes you do have active
96 copyright assignment papers with the FSF, for future changes to either
97 Org mode or to Emacs, this means that copyright to these changes is
98 automatically transferred to the FSF.
100 The Org mode repository is seen as upstream repository for Emacs,
101 anything contained in it can potentially end up in Emacs. If you do
102 not have signed papers with the FSF, only changes to files in the
103 =contrib/= part of the repository will be accepted, as well as very
104 minor changes (so-called /tiny changes/) to core files. We will ask you
105 to sign FSF papers at the moment we attempt to move a =contrib/= file
106 into the Org core, or into Emacs.
113 Org developers are those who have write access to the repository.
117 Please read Worg's page on [[https://orgmode.org/worg/org-maintainance.html][Org maintainance]].
119 ** Pushing your first commit
121 1. Send [[mailto:bzgATgnuDOTorg][Bastien]] the username you want for https://code.orgmode.org
122 2. Add your public key to your account, once its creation is confirmed
123 3. Clone =org-mode.git=: =~$ git clone git@code.orgmode.org:bzg/org-mode.git=
124 4. Commit your changes against the code and the documentation
126 6. If the tests pass, push your changes
128 If you are undertaking big changes, please create a dedicated branch
129 locally and make sure you have a clean commit history before merging
130 it into the maint or master branch.
132 * For Org contributors: preferred way of submitting patches
137 ** Coding conventions
139 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
140 Lisp coding conventions]] described in Emacs manual.
142 ** Sending patch with git
144 Please use Git to make patches and send them via email -- this is
145 perfectly fine for major and minor changes.
147 When sending a patch (either using =git diff= or =git format-patch=)
148 please *always add a properly formatted Emacs ChangeLog entry*. See
149 [[#commit-messages][this section]] for details on how to create such a ChangeLog.
153 For every patch you send, we suggest to use =git format-patch=.
155 This is easy for small patches and more consequent ones. Sometimes,
156 you might even want to work in several steps and send each commit
157 separately. Here is the suggested workflow:
160 : ~$ git pull # make sure your repo is up to date
161 : ~$ git branch my-changes # create a new branch from master
162 : ~$ git checkout my-changes # switch to this new branch
164 ... make some changes (1) ...
166 : ~$ git commit -a -m "This is change (1)" # Commit your change
168 ... make another change (2) ...
170 : ~$ git commit -a -m "This is change (2)" # Commit your change
171 : ~$ git format-patch master # Creates two patches
173 ... Then two patches for your two commits are ready to be sent to
177 To finally send the patches, you can either add them as attachments to
178 your email, or use [[https://git-scm.com/docs/git-send-email][git send-email]], if it's properly configured.
180 Write useful commit messages: please provide 1) a reason for it in
181 your email and 2) a ChangeLog entry in the commit message (see [[#commit-messages][this
182 section]] on how to format a ChangeLog entry.)
184 ** Sending quick fixes for testing purpose
186 If you want to send a quick fix that needs to be further tested by
187 other people (before you submit a real patch), here is how you can do:
190 This command will make a patch between the staging area (in your
191 computer), and the file you modified:
193 : git diff -p org-whatever.el > org-whatever.el.diff
195 If you already committed your changes to your index (staging area), then
196 you should compare against a particular branch (in this example,
199 : git diff -p origin/master org-whatever.el > org-whatever.el.diff
201 You email the output to the mailing list, adding =[PATCH]= to the
202 subject, and description of what you fixed or changed.
205 Note that small patches sent like this still need to have a ChangeLog
206 entry to be applied. If your patch looks good to you, it's always
207 better to send a patch through =git format-patch=.
209 ** Sharing changes from a public branch
211 When discussing important changes, it is sometimes not so useful to
212 send long and/or numerous patches.
214 In this case, you can maintain your changes on a public branch of a
215 public clone of Org and send a link to the diff between your changes
216 and the latest Org commit that sits in your clone.
218 If the discussion settles and your change is accepted, you can now
219 send it as (a list of) patch(es) to the latest Org version.
221 * Commit messages and ChangeLog entries
223 :CUSTOM_ID: commit-messages
226 We have decided to no longer keep a ChangeLog file to record changes
227 to individual functions.
229 A commit message should be constructed in the following way:
231 - Line 1 of the commit message should always be a short description of
232 the overall change. Line 1 does /not/ get a dot at the end and does
233 not start with a star. Generally, it starts with the filename that
234 has been changed, followed by a colon.
236 - Line 2 is an empty line.
238 - In line 3, the ChangeLog entry should start. A ChangeLog entry
239 looks like [[https://orgmode.org/cgit.cgi/org-mode.git/commit/?id%3Dd49957ef021e256f19092c907d127390d39ec1ed][this]]:
241 : * org-timer.el (org-timer-cancel-timer, org-timer-stop): Enhance
243 : (org-timer-set-timer): Use the number of minutes in the Effort
244 : property as the default timer value. Three prefix arguments will
245 : ignore the Effort value property.
247 - After the changelog, another empty line should come before any
248 additional information that the committer wishes to provide in order
249 to explain the patch.
251 - If the change is a minor change made by a committer without
252 copyright assignment to the FSF, the commit message should also
253 contain the cookie =TINYCHANGE= (anywhere in the message). When we
254 later produce the ChangeLog file for Emacs, the change will be
255 marked appropriately.
257 - Variables and functions names are quoted like `this' (backquote and
260 - Sentences should be separated by two spaces.
262 - Sentences should start with an uppercase letter.
264 - Avoid the passive form: i.e., use "change" instead of "changed".
266 Here is an example for such a message:
269 org-capture.el: Fix the case of using a template file
271 ,* lisp/org-capture.el (org-capture-set-plist): Make sure txt is a
272 string before calling `string-match'.
273 (org-capture-templates): Fix customization type.
275 ,* doc/org.texi (Capture): Document using a file for a template.
277 The problem here was that a wrong keyword was given in the
278 customization type. This let to a string-match against a list value.
280 Modified from a patch proposal by Johan Friis.
285 If you are using /magit.el/ in Emacs, the ChangeLog for such entries are
286 easily produced by pressing =C= in the diff listing.
288 Another option to produce the entries is to use `C-x 4 a' in the
289 changed function or in the diff listing. This will create entries in
290 the ChangeLog file, and you can then cut and paste these to the commit
291 message and remove the indentation.
293 - Further reference: [[http://git.savannah.gnu.org/cgit/emacs.git/plain/CONTRIBUTE][Contribution guide from Emacs repo]]
295 * Copyrighted contributors to Org mode
297 :CUSTOM_ID: copyrighted-contributors
300 Here is the list of people who have contributed actual code to the Org
301 mode core. Note that the manual contains a more extensive list with
302 acknowledgments, including contributed ideas! The lists below are
303 mostly for house keeping, to help the maintainers keep track of
306 ** Current contributors
308 :CUSTOM_ID: contributors_with_fsf_papers
311 Here is the list of people who signed the papers with the Free Software
312 Foundation and can now freely submit code to Org files that are included
329 - Andrzej Lichnerowicz
336 - Barry Leonard Gidden
352 - Christopher Miles Gray
353 - Christopher Schmidt
354 - Christopher Suckling
355 - Clément Pit--Claudel
358 - Daniel M.\nbsp{}Hackney
359 - David Arroyo Menéndez
366 - Emmanuel Charpentier
369 - Eric S.\nbsp{}Fraga
375 - Francesco Pizzolante
378 - George Kettleborough
382 - Grégoire Jadi (aka Daimrod)
384 - Henning Dietmar Weiss
408 - Jonathan Leech-Pepin
410 - José L.\nbsp{}Doménech
420 - Kevin Brubeck Unhammer
429 - Leonard Avery Randall
440 - Mark A.\nbsp{}Hershberger
449 - Miguel A.\nbsp{}Figueroa-Villanueva
463 - No Wayman (Nicholas Vollmer)
466 - Pedro Alexandre Marcelino Costa da Silva
477 - Rasmus Pank Roulund
482 - Robert Michael Irelan
496 - Siraphob Phipathananunth
510 - Thomas S.\nbsp{}Dye
514 - Timothy E Chapman (TEC)
515 - Titus von der Malsburg
530 - Yuri D.\nbsp{}Lensky
532 - Zhuo Qingliang (Killy Draw)
536 These people have been asked to sign the papers, and they are
537 currently considering it or a request is being processed by the FSF.
539 - Felipe Lema [2020-02-25 mar.]
540 - Terje Larsen [2020-02-17 lun.]
541 - Brian Carlson [2016-05-24 Tue]
542 - Mats Kindahl (as of 2013-04-06) for [[http://mid.gmane.org/513BAB7D.1000603@oracle.com][this patch]]
547 These people have submitted tiny change patches that made it into Org
548 without FSF papers. When they submit more, we need to get papers
549 eventually. The limit is a cumulative change of 20 non-repetitive
550 change lines. Details are given in [[http://www.gnu.org/prep/maintain/maintain.html#Legally-Significant ][this document]].
552 - Aaron L.\nbsp{}Zeng
553 - Abhishek Chandratre
557 - Alexandru-Sergiu Marton
567 - Arne Babenhauserheide
578 - Christian Schwarzgruber
595 - Francesco Montanari
600 - Greg Tucker-Kellogg
603 - Ivan Vilata i Balaguer
613 - Joaquín Aguirrezabalaga
622 - Konstantin Kliakhandler
624 - Leslie Harlley Watter
661 - Richard Y.\nbsp{}Kim (Kim)
664 - Robert P.\nbsp{}Goldman
668 - Saulius Menkevičius
669 - Sebastien Le Maguer
676 - Stefan-W.\nbsp{}Hahn
683 - Thomas Alexander Gerds
693 - Xavier Martinez-Hidalgo
698 - Zane D.\nbsp{}Purvis
701 (This list may be incomplete - please help completing it.)
705 These people cannot or prefer to not sign the FSF copyright papers,
706 and we can only accept patches that do not change the core files (the
707 ones that are also in Emacs).
709 Luckily, this list is still empty.
711 #+BEGIN: timestamp :string "Last update: " :format "%Y-%m-%d @ %H:%M"