org-contrib/index.org: Point org-drill.org outside of org-contrib/
[worg.git] / org-contribute.org
blobc8dbbf8a43bf5670947031eb557af2fd1555d175
1 #+TITLE:      How to contribute to Org?
2 #+AUTHOR:     Worg people
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)
8 #+LANGUAGE:   en
9 #+PRIORITIES: A C B
10 #+CATEGORY:   worg
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
18 :PROPERTIES:
19 :CUSTOM_ID: types-of-contributions
20 :END:
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
49   examples.
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
53     it with people.
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
61     GNU Emacs.
63 * Copyright issues when contributing to Emacs Org mode
64 :PROPERTIES:
65 :CUSTOM_ID: copyright-issues
66 :END:
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
78 process is complete.
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
82 contributors?]]
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.
88 #+begin_example
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.
93 #+end_example
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.
108 * For Org developers
109   :PROPERTIES:
110   :CUSTOM_ID: devs
111   :END:
113 Org developers are those who have write access to the repository.
115 ** Git branches
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
125 5. Run =make test=
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
133 :PROPERTIES:
134 :CUSTOM_ID: patches
135 :END:
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.
151 ** Sending commits
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:
159 #+begin_quote
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
174   the list.
175 #+end_quote
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:
189 #+begin_quote
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,
197   origin/master):
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.
203 #+end_quote
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
222 :PROPERTIES:
223 :CUSTOM_ID: commit-messages
224 :END:
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
242   : message.
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
258   single quote).
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:
268 #+begin_example
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.
282   TINYCHANGE
283 #+end_example
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
296 :PROPERTIES:
297 :CUSTOM_ID: copyrighted-contributors
298 :END:
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
304 copyright issues.
306 ** Current contributors
307   :PROPERTIES:
308   :CUSTOM_ID: contributors_with_fsf_papers
309   :END:
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
313 within GNU Emacs:
315 - Aaron Ecay
316 - Aaron Jensen
317 - Abdó Roig-Maranges
318 - Achim Gratz
319 - Adam Elliott
320 - Adam Porter
321 - Adam Spiers
322 - Alan Schmitt
323 - Alex Branham
324 - Alexey Lebedeff
325 - Allen Li
326 - Andreas Burtzlaff
327 - Andreas Leha
328 - Andrew Hyatt
329 - Andrzej Lichnerowicz
330 - Andy Steward
331 - Anthony John Day
332 - Anthony Lander
333 - Arni Magnusson
334 - Arun Isaac
335 - Baoqiu Cui
336 - Barry Leonard Gidden
337 - Bastien Guerry
338 - Benjamin Andresen
339 - Bernd Grobauer
340 - Bernt Hansen
341 - Bjarte Johansen
342 - Brian James Gough
343 - Brice Waegenire
344 - Carlos Pita
345 - Carsten Dominik
346 - Charles Berry
347 - Charles Sebold
348 - Christian Egli
349 - Christian Garbs
350 - Christian Moe
351 - Christopher League
352 - Christopher Miles Gray
353 - Christopher Schmidt
354 - Christopher Suckling
355 - Clément Pit--Claudel
356 - Dan Davison
357 - Daniel M German
358 - Daniel M.\nbsp{}Hackney
359 - David Arroyo Menéndez
360 - David Maus
361 - David O'Toole
362 - Dieter Schoen
363 - Dima Kogan
364 - Dmitry Antipov
365 - Don March
366 - Emmanuel Charpentier
367 - Eric Abrahamsen
368 - Eric Schulte
369 - Eric S.\nbsp{}Fraga
370 - Erik Hetzner
371 - Erik Iverson
372 - Ethan Ligon
373 - Feng Shu
374 - Florian Lindner
375 - Francesco Pizzolante
376 - Frederick Giasson
377 - Gary Oberbrunner
378 - George Kettleborough
379 - Georg Lehner
380 - Giovanni Ridolfi
381 - Greg Minshall
382 - Grégoire Jadi (aka Daimrod)
383 - Gustav Wikström
384 - Henning Dietmar Weiss
385 - Henry Blevins
386 - Ian Barton
387 - Ian Dunn
388 - Ian Kelling
389 - Ilya Shlyakhter
390 - Ingo Lohmar
391 - Ippei Furuhashi
392 - Jack Kamm
393 - Jake Romer
394 - James TD Smith
395 - Jan Böcker
396 - Jan Malakhovski
397 - Jarmo Hurri
398 - Jason Riedy
399 - Jay Kamat
400 - Jay Kerns
401 - Jeffrey Ryan Horn
402 - Jens Lechtenboerg
403 - Joe Corneli
404 - Joel Boehland
405 - John Kitchin
406 - John Wiegley
407 - Jonas Bernoulli
408 - Jonathan Leech-Pepin
409 - Jon Snader
410 - José L.\nbsp{}Doménech
411 - Juan Pechiar
412 - Julian Gehring
413 - Julien Barnier
414 - Julien Danjou
415 - Justin Gordon
416 - Justus Piater
417 - Karl Fogel
418 - Kaushal Modi
419 - Ken Mankoff
420 - Kevin Brubeck Unhammer
421 - Kevin Foley
422 - Kévin Le Gouguec
423 - Konstantin Antipin
424 - Kyle Meyer
425 - Lambda Coder
426 - Lawrence Mitchell
427 - Lele Gaifax
428 - Lennart Borgman
429 - Leonard Avery Randall
430 - Leo Vivier
431 - Le Wang
432 - Luis Anaya
433 - Lukasz Stelmach
434 - Madan Ramakrishnan
435 - Magnus Henoch
436 - Manuel Giraud
437 - Marcin Borkowski
438 - Marco Wahl
439 - Mario Frasca
440 - Mark A.\nbsp{}Hershberger
441 - Martin Pohlack
442 - Martyn Jago
443 - Matt Lundin
444 - Max Mikhanosha
445 - Michael Albinus
446 - Michael Brand
447 - Michael Gauland
448 - Michael Sperber
449 - Miguel A.\nbsp{}Figueroa-Villanueva
450 - Mikael Fornius
451 - Moritz Ulrich
452 - Nathaniel Flath
453 - Nathan Neff
454 - Neil Jerram
455 - Nicholas Dokos
456 - Nicolas Berthier
457 - Nicolas Dudebout
458 - Nicolas Goaziou
459 - Nicolas Richard
460 - Niels Giessen
461 - Nikolai Weibull
462 - Noorul Islam K M
463 - No Wayman (Nicholas Vollmer)
464 - Oleh Krehel
465 - Paul Sexton
466 - Pedro Alexandre Marcelino Costa da Silva
467 - Peter Jones
468 - Phil Hudson
469 - Philip Rooke
470 - Phil Jackson
471 - Pierre Téchoueyres
472 - Pieter Praet
473 - Piotr Zielinski
474 - Puneeth Chaganti
475 - Rafael Laboissière
476 - Rainer M Krug
477 - Rasmus Pank Roulund
478 - Richard Kim
479 - Richard Klinda
480 - Richard Riley
481 - Rick Frankel
482 - Robert Michael Irelan
483 - Roland Coeurjoly
484 - Rüdiger Sonderfeld
485 - Russell Adams
486 - Ryo Takaishi
487 - Sacha Chua
488 - Samuel Loury
489 - Sebastian Miele
490 - Sebastian Reuße
491 - Sebastian Rose
492 - Sebastien Vauban
493 - Sergey Litvinov
494 - Seweryn Kokot
495 - Simon Michael
496 - Siraphob Phipathananunth
497 - stardiviner
498 - Stefan Kangas
499 - Stephen Eglen
500 - Steven Rémot
501 - Suvayu Ali
502 - Takaaki Ishikawa
503 - Tassilo Horn
504 - T.F. Torrey
505 - Thibault Marin
506 - Thierry Banel
507 - Thomas Baumann
508 - Thomas Fitzsimmons
509 - Thomas Holst
510 - Thomas S.\nbsp{}Dye
511 - Thorsten Jolitz
512 - Tim Burt
513 - Tim Landscheidt
514 - Timothy E Chapman (TEC)
515 - Titus von der Malsburg
516 - Toby Cubitt
517 - Tokuya Kameshima
518 - Tomas Hlavaty
519 - Tom Breton
520 - Tom Gillespie
521 - Tony Day
522 - Toon Claes
523 - Trevor Murphy
524 - Ulf Stegemann
525 - Vitalie Spinu
526 - Vladimir Panteleev
527 - Yann Hodique
528 - Yasushi Shoji
529 - Yoshinari Nomura
530 - Yuri D.\nbsp{}Lensky
531 - Zhang Weize
532 - Zhuo Qingliang (Killy Draw)
534 ** Processing
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]]
543 - Bill Wishon [?]
545 ** Tiny Changes
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
554 - Adam Aviv
555 - akater
556 - Albert Krewinkel
557 - Alexandru-Sergiu Marton
558 - Aliaksey Artamonau
559 - Aman Yang
560 - Anders Johansson
561 - Andrew Burgess
562 - Andrew Eggenberger
563 - Andrii Kolomoiets
564 - Andy Lutomirski
565 - Anthony Cowley
566 - Anton Latukha
567 - Arne Babenhauserheide
568 - Arun Persaud
569 - Augustin Fabre
570 - Aurélien Aptel
571 - Austin Walker
572 - Axel Kielhorn
573 - Benson Chu
574 - Brad Knotwell
575 - Brian Powell
576 - Cheong Yiu Fung
577 - Christian Hopps
578 - Christian Schwarzgruber
579 - Chunyang Xu
580 - Claudiu Tănăselia
581 - Craig Tanis
582 - Dan Drake
583 - Daniel Peres Gomez
584 - Derek Feichtinger
585 - Dima Gerasimov
586 - Dominik Schrempf
587 - Doro Rose
588 - Eduardo Bellani
589 - Eric Danan
590 - Eric Timmons
591 - Federico Beffa
592 - Feng Zhou
593 - Fernando Varesi
594 - Florian Beck
595 - Francesco Montanari
596 - Galen Menzel
597 - Georgiy Tugai
598 - Gong Qijian
599 - Gregor Zattler
600 - Greg Tucker-Kellogg
601 - Hiroshi Saito
602 - Ihor Radchenko
603 - Ivan Vilata i Balaguer
604 - Jack Henahan
605 - Jacob Gerlach
606 - Jacob Matthews
607 - Jakob Lombacher
608 - Jamie Forth
609 - Jan Seeger
610 - Jason Dunsmore
611 - Jason Furtney
612 - Jeff Larson
613 - Joaquín Aguirrezabalaga
614 - Joe Hirn
615 - John Foerch
616 - John Lee
617 - Jonas Hörsch
618 - Jon Miller
619 - Joost Diepenmaat
620 - Jose Robins
621 - Kodi Arfer
622 - Konstantin Kliakhandler
623 - Kovacsics Robert
624 - Leslie Harlley Watter
625 - Leslie Watter
626 - Lixin Chin
627 - Luke Amdor
628 - Mak Kolybabi
629 - Marc Ihm
630 - Mario Martelli
631 - Marshall Flax
632 - Martin Šlouf
633 - Martin Vuk
634 - Matthew Gidden
635 - Matthew MacLean
636 - Matt Huszagh
637 - Matt Price
638 - Max Mouratov
639 - Michaël Cadilhac
640 - Michael O'Connor
641 - Michael Strey
642 - Michael Welle
643 - Michael Weylandt
644 - Mike Ivanov
645 - Mike McLean
646 - Miro Bezjak
647 - Moritz Kiefer
648 - Muchenxuan Tong
649 - Myles English
650 - Myq Larson
651 - Nathaniel Nicandro
652 - Nick Gunn
653 - Nicolò Balzarotti
654 - Peter Feigl
655 - Peter Moresi
656 - Philip (Pip Cet)
657 - Piet van Oostrum
658 - Renato Ferreira
659 - Richard Hansen
660 - Richard Lawrence
661 - Richard Y.\nbsp{}Kim (Kim)
662 - Robert Hambrock
663 - Roberto Huelga
664 - Robert P.\nbsp{}Goldman
665 - Roger Welsh
666 - Ruben Maher
667 - Sami Airaksinen
668 - Saulius Menkevičius
669 - Sebastien Le Maguer
670 - Sergey Gordienko
671 - Seth Robertson
672 - Sigmund Tzeng
673 - Stacey Marshall
674 - Stanley Jaddoe
675 - Stefano Rodighiero
676 - Stefan-W.\nbsp{}Hahn
677 - Stig Brautaset
678 - Sylvain Chouleur
679 - Tadashi Hirata
680 - Teika Kazura
681 - Terje Larsen
682 - Thierry Pellé
683 - Thomas Alexander Gerds
684 - Thomas Plass
685 - Thomas Rikl
686 - Tim Visher
687 - Tobias Schlemmer
688 - Tom Hinton
689 - Vicente Vera Parra
690 - Viktor Rosenfeld
691 - Vladimir Lomov
692 - Wojciech Gac
693 - Xavier Martinez-Hidalgo
694 - Xi Shen
695 - Yann Esposito
696 - York Zhao
697 - Yue Zhu
698 - Zane D.\nbsp{}Purvis
699 - Иван Трусков
701 (This list may be incomplete - please help completing it.)
703 ** No FSF assignment
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"
713 #+END: