Update

[worg.git] / org-contribute.org

#+TITLE:      How to contribute to Org?
#+AUTHOR:     Worg people
#+EMAIL:      mdl AT imapmail DOT org
#+OPTIONS:    H:3 num:nil toc:t \n:nil ::t |:t ^:nil -:t f:t *:t tex:t d:(HIDE) tags:not-in-toc
#+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
#+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
#+TAGS:       Write(w) Update(u) Fix(f) Check(c)
#+LANGUAGE:   en
#+PRIORITIES: A C B
#+CATEGORY:   worg

# This file is the default header for new Org files in Worg.  Feel free
# to tailor it to your needs.

[[file:index.org][{Back to Worg's index}]]

* Types of contributions
:PROPERTIES:
:CUSTOM_ID: types-of-contributions
:END:

Every contribution to Org is very welcome.  Here is a list of areas
where your contribution will be useful:

- you can submit *bug reports* -- Before sending a bug report, make sure
  you have read this section of Org's manual: [[https://orgmode.org/org.html#Feedback][Feedback]] You can also
  read this great text: "[[http://www.chiark.greenend.org.uk/~sgtatham/bugs.html][How to Send Bug Reports Effectively]]"

- you can submit *patches* -- You can submit patches to the mailing
  list.  See the [[For Org contributors: preferred way of submitting patches][Preferred way of submitting patches]] section for
  details.  You can run =make test= to check that your patch does not
  introduce new bugs.

  If your patch is against a file that is part of Emacs, then your
  total contribution (all patches you submit) should change /less than
  15 lines/ (See the [[http://git.savannah.gnu.org/cgit/emacs.git/tree/CONTRIBUTE][CONTRIBUTE file in GNU Emacs]].)  If you contribute
  more, you have to assign the copyright of your contribution to the
  Free Software Foundation (see below).

- You can submit material to the *Worg* website -- This website is made
  of Org files that you can contribute to.  Learn what Worg is [[file:worg-about.org][about]]
  and how to contribute to it [[file:worg-git.org][through git]].

- You can submit *feature requests* -- Org is already mature, but new
  ideas keep popping up.  If you want to request a feature, it might
  be a good idea to have a look at the current [[https://orgmode.org/worg/org-issues.html][Issue tracking file]]
  which captures both bug reports and feature requests.  Or dig into
  the mailing list for possible previous discussions about your idea.
  If you cannot find back your idea, formulate it as detailed as
  possible, if possible with examples, and send it to the mailing
  list.

- You can submit Org *add-ons* -- there are many Org add-ons.
  - The best way is to submit your code to [[file:org-mailing-list.org][the mailing list]] to discuss
    it with people.
  - If it is useful, you might consider contributing it to the
    =lisp/contrib/= directory in the git repository.  It will be
    reviewed, and if it passes, it will be included.  Ask help from
    [[file:org-people.org][Eric Schulte]] for this step.  The =lisp/contrib/= directory is
    somehow relaxed: it is not distributed with Emacs, and does not
    require a formal copyright assignment.
  - If you decide to sign the [[*Copyright issues when contributing to Emacs Org mode][assignment contract with the FSF]], we
    might include your contribution in the distribution, and then in
    GNU Emacs.

* Copyright issues when contributing to Emacs Org mode
:PROPERTIES:
:CUSTOM_ID: copyright-issues
:END:

Org is made of many files.  Most of them are also distributed as part
of GNU Emacs.  These files are called the /Org core/, and they are all
copyrighted by the [[http://www.fsf.org][Free Software Foundation, Inc]].  If you consider
contributing to these files, your first need to grant the right to
include your works in GNU Emacs to the FSF.  For this you need to
complete [[https://orgmode.org/request-assign-future.txt][this form]], and send it to [[mailto:assign@gnu.org][assign@gnu.org]].  The FSF will send
you the assignment contract that both you and the FSF will sign.
Please let the Org mode maintainer know when this process is complete.
Some people consider this assignment process a hassle.  I don't want
to discuss this in detail here - there are some good reasons for
getting the copyright registered, an example is discussed in this
[[http://twit.tv/floss117][FLOSS weekly podcast]].  Furthermore, by playing according to the Emacs
rules, we gain the fantastic advantage that every version of Emacs
ships with Org mode already fully built in.  So please consider doing
this - it makes our work as maintainers so much easier, because we can
then take your patches without any additional work.

If you want to learn more about /why/ copyright assignments are
collected, read this: [[http://www.gnu.org/licenses/why-assign.html][Why the FSF gets copyright assignments from
contributors?]]

By submitting patches to emacs-orgmode@gnu.org, or by pushing changes
to the Org mode repository, you are placing these changes under the
same licensing terms as those under which GNU Emacs is published.

#+begin_example
;; GNU Emacs is free software: you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
#+end_example

If at the time you submit or push these changes you do have active
copyright assignment papers with the FSF, for future changes to either
Org mode or to Emacs, this means that copyright to these changes is
automatically transferred to the FSF.  The Org mode repository is seen
as upstream repository for Emacs, anything contained in it can
potentially end up in Emacs.  If you do not have signed papers with
the FSF, only changes to files in the =contrib/= part of the repository
will be accepted, as well as very minor changes (so-called /tiny
changes/) to core files.  We will ask you to sign FSF papers at the
moment we attempt to move a =contrib/= file into the Org core, or into
Emacs.

* For Org developers
  :PROPERTIES:
  :CUSTOM_ID: devs
  :END:

** Git branches

Please read [[https://code.orgmode.org/bzg/org-mode/src/master/README_maintainer][README_maintainer]] file within Org's repository.

** Pushing your first commit

1. Create an account on https://code.orgmode.org
2. Add your public key to the account
3. Ask [[mailto:bzgATgnuDOTorg][Bastien]] to be added as a collaborator on the repository
4. Clone =org-mode.git=: =~$ git clone git@code.orgmode.org:bzg/org-mode.git=
5. Commit your changes against the code and the documentation.
6. Run =make test=
7. If the tests pass, push your changes.

If you are undertaking big changes, please create a dedicated branch
and make sure you have a clean commit history before merging it into
the maint or master branch.

** Taking care of the manual in both branches

- When you make a change in the master branch, update
  doc/org-manual.org accordingly.

- When you make a change in the maint branch, update doc/org.texi in
  maint and doc/org-manual.org when you merge maint into master.

* For Org contributors: preferred way of submitting patches
:PROPERTIES:
:CUSTOM_ID: patches
:END:

** Coding conventions

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
Lisp coding conventions]] described in Emacs manual.

** Sending patch with git

Org mode is developed using /git/ as the version control system.  Git
provides an amazing framework to collaborate on a project.  Git can be
used to make patches and send them via email -- this is perfectly fine
for major and minor changes.

When sending a patch (either using =git diff= or =git format-patch=)
please *always add a properly formatted Emacs ChangeLog entry*.  See
[[#commit-messages][this section]] for details on how to create such a ChangeLog.

** Sending commits

For every patch you send, we suggest to use =git format-patch=.

This is easy for small patches and more consequent ones.  Sometimes,
you might even want to work in several steps and send each commit
separately.  Here is the suggested workflow:

#+begin_quote
:   ~$ git pull                 # make sure your repo is up to date
:   ~$ git branch my-changes    # create a new branch from master
:   ~$ git checkout my-changes  # switch to this new branch

  ... make some changes (1) ...

:   ~$ git commit -a -m "This is change (1)"  # Commit your change

  ... make another change (2) ...

:   ~$ git commit -a -m "This is change (2)"  # Commit your change
:   ~$ git format-patch master                # Creates two patches

  ... Then two patches for your two commits are ready to be sent to
  the list.
#+end_quote

Write useful commit messages: please provide 1) a reason for it in
your email and 2) a ChangeLog entry in the commit message (see [[#commit-messages][this section]] on how to format a ChangeLog entry.)

** Sending quick fixes for testing purpose

If you want to send a quick fix that needs to be further tested by
other people (before you submit a real patch), here is how you can do:

#+begin_quote
  This command will make a patch between the staging area (in your
  computer), and the file you modified:

  : git diff -p org-whatever.el > org-whatever.el.diff

  If you already committed your changes to your index (staging area), then
  you should compare against a particular branch (in this example,
  origin/master):

  : git diff -p origin/master org-whatever.el > org-whatever.el.diff

  You email the output to the mailing list, adding =[PATCH]= to the
  subject, and description of what you fixed or changed.
#+end_quote

Note that small patches sent like this still need to have a ChangeLog
entry to be applied.  If your patch looks good to you, it's always
better to send a patch through =git format-patch=.

** Sharing changes from a public branch

For more significant contributions, the best way to submit patches is
through public branches of your repository clone.

1. Clone our git repository at =https://code.orgmode.org/bzg/org-mode=.
   You can clone using any of the commands below.

   : git clone git@code.orgmode.org:bzg/org-mode.git
   : git clone https://code.orgmode.org/bzg/org-mode.git

   The url using the git protocol is preferred.  If you are behind a
   firewall that blocks ~git://~, you can use the https url.

2. Create a repository that can be publicly accessed, for example on
   /GitHub/ or on your own server.

3. Push your topic branches (and optionally the master branch) to your
   public repository.

   Define a remote for your public repository you push topics to.

   : git remote add REMOTE URL-GOES-HERE

   Push branches to the remote

   : git push REMOTE BRANCH1 [BRANCH2 BRANCH3 ...]

   e.g.

   : git remote add github ssh://.../     # Done once to define the remote 'github'
   : git push github my-topic

4. Do your work on topic-specific branches, using a branch name that
   relates to what you are working on.

5. Often do

   : git remote update

   to pull commits from all defined remote repositories.

6. When you have something workable, publish the git path and branch
   name on the mailing list, so that people can test it and review
   your work.

7. After your topic has been merged to the project master branch you
   can delete the topic on your local and remote repositories.

   : git branch -d NEWTOPIC
   : git push REMOTE :NEWTOPIC

The instructions above are generally useful to let people test new
features before sending the patch series to the mailing list, but the
patches remain the preferred way of receiving contributions.

* Commit messages and ChangeLog entries
:PROPERTIES:
:CUSTOM_ID: commit-messages
:END:

We have decided to no longer keep a ChangeLog file to record changes
to individual functions.

A commit message should be constructed in the following way:

- Line 1 of the commit message should always be a short description of
  the overall change.  Line 1 does /not/ get a dot at the end and does
  not start with a star.  Generally, it starts with the filename that
  has been changed, followed by a colon.

- Line 2 is an empty line.

- In line 3, the ChangeLog entry should start.  A ChangeLog entry
  looks like [[https://orgmode.org/cgit.cgi/org-mode.git/commit/?id%3Dd49957ef021e256f19092c907d127390d39ec1ed][this]]:

  : * org-timer.el (org-timer-cancel-timer, org-timer-stop): Enhance
  : message.
  : (org-timer-set-timer): Use the number of minutes in the Effort
  : property as the default timer value. Three prefix arguments will
  : ignore the Effort value property.

- After the changelog, another empty line should come before any
  additional information that the committer wishes to provide in order
  to explain the patch.

- If the change is a minor change made by a committer without
  copyright assignment to the FSF, the commit message should also
  contain the cookie =TINYCHANGE= (anywhere in the message).  When we
  later produce the ChangeLog file for Emacs, the change will be
  marked appropriately.

- Variables and functions names are quoted like `this' (backquote and
  single quote).

- Sentences should be separated by two spaces.

- Sentences should start with an uppercase letter.

- Avoid the passive form: i.e., use "change" instead of "changed".

Here is an example for such a message:

#+begin_example
  org-capture.el: Fix the case of using a template file

  ,* lisp/org-capture.el (org-capture-set-plist): Make sure txt is a
  string before calling `string-match'.
  (org-capture-templates): Fix customization type.

  ,* doc/org.texi (Capture): Document using a file for a template.

  The problem here was that a wrong keyword was given in the
  customization type.  This let to a string-match against a list value.

  Modified from a patch proposal by Johan Friis.

  TINYCHANGE
#+end_example

If you are using /magit.el/ in Emacs, the ChangeLog for such entries
are easily produced by pressing =C= in the diff listing.

Another option to produce the entries is to use `C-x 4 a' in the
changed function or in the diff listing.  This will create entries in
the ChangeLog file, and you can then cut and paste these to the commit
message and remove the indentation.

- Further reference: [[http://git.savannah.gnu.org/cgit/emacs.git/plain/CONTRIBUTE][Contribution guide from Emacs repo]]

* Copyrighted contributors to Org mode
:PROPERTIES:
:CUSTOM_ID: copyrighted-contributors
:END:

Here is the list of people who have contributed actual code to the Org
mode core.  Note that the manual contains a more extensive list with
acknowledgments, including contributed ideas!  The lists below are
mostly for house keeping, to help the maintainers keep track of
copyright issues.

** Current contributors
  :PROPERTIES:
  :CUSTOM_ID: contributors_with_fsf_papers
  :END:

Here is the list of people who signed the papers with the Free Software
Foundation and can now freely submit code to Org files that are included
within GNU Emacs:

1. Aaron Ecay
2. Aaron Jensen
3. Abdó Roig-Maranges
4. Achim Gratz
5. Adam Elliott
6. Adam Porter
7. Adam Spiers
8. Alan Schmitt
9. Alex Branham
10. Alexey Lebedeff
11. Allen Li
12. Andreas Burtzlaff
13. Andreas Leha
14. Andrew Hyatt
15. Andrzej Lichnerowicz
16. Andy Steward
17. Anthony John Day
18. Anthony Lander
19. Arni Magnusson
20. Arun Isaac
21. Baoqiu Cui
22. Barry Leonard Gidden
23. Bastien Guerry
24. Benjamin Andresen
25. Bernd Grobauer
26. Bernt Hansen
27. Bjarte Johansen
28. Brian James Gough
29. Brice Waegenire
30. Carlos Pita
31. Carsten Dominik
32. Charles Berry
33. Charles Sebold
34. Christian Egli
35. Christian Garbs
36. Christian Moe
37. Christopher League
38. Christopher Miles Gray
39. Christopher Schmidt
40. Christopher Suckling
41. Clément Pit--Claudel
42. Dan Davison
43. Daniel M German
44. Daniel M.\nbsp{}Hackney
45. David Arroyo Menéndez
46. David Maus
47. David O'Toole
48. Dieter Schoen
49. Dima Kogan
50. Dmitry Antipov
51. Don March
52. Emmanuel Charpentier
53. Eric Abrahamsen
54. Eric Schulte
55. Eric S.\nbsp{}Fraga
56. Erik Hetzner
57. Erik Iverson
58. Ethan Ligon
59. Feng Shu
60. Florian Lindner
61. Francesco Pizzolante
62. Frederick Giasson
63. Gary Oberbrunner
64. George Kettleborough
65. Georg Lehner
66. Giovanni Ridolfi
67. Grégoire Jadi (aka Daimrod)
68. Gustav Wikström
69. Henning Dietmar Weiss
70. Henry Blevins
71. Ian Barton
72. Ian Dunn
73. Ian Kelling
74. Ilya Shlyakhter
75. Ingo Lohmar
76. Ippei Furuhashi
77. Jack Kamm
78. Jake Romer
79. James TD Smith
80. Jan Böcker
81. Jan Malakhovski
82. Jarmo Hurri
83. Jason Riedy
84. Jay Kamat
85. Jay Kerns
86. Jeffrey Ryan Horn
87. Jens Lechtenboerg
88. Joe Corneli
89. Joel Boehland
90. John Kitchin
91. John Wiegley
92. Jonas Bernoulli
93. Jonathan Leech-Pepin
94. Jon Snader
95. José L.\nbsp{}Doménech
96. Juan Pechiar
97. Julian Gehring
98. Julien Barnier
99. Julien Danjou
100. Justin Gordon
101. Justus Piater
102. Karl Fogel
103. Kaushal Modi
104. Kevin Brubeck Unhammer
105. Kodi Arfer
106. Konstantin Antipin
107. Kyle Meyer
108. Lambda Coder
109. Lawrence Mitchell
110. Lele Gaifax
111. Lennart Borgman
112. Leonard Avery Randall
113. Le Wang
114. Luis Anaya
115. Lukasz Stelmach
116. Madan Ramakrishnan
117. Magnus Henoch
118. Manuel Giraud
119. Marcin Borkowski
120. Marco Wahl
121. Mark A.\nbsp{}Hershberger
122. Martin Pohlack
123. Martyn Jago
124. Matt Lundin
125. Max Mikhanosha
126. Michael Albinus
127. Michael Brand
128. Michael Gauland
129. Michael Sperber
130. Miguel A.\nbsp{}Figueroa-Villanueva
131. Mikael Fornius
132. Moritz Ulrich
133. Nathaniel Flath
134. Nathan Neff
135. Neil Jerram
136. Nicholas Dokos
137. Nicolas Berthier
138. Nicolas Dudebout
139. Nicolas Goaziou
140. Nicolas Richard
141. Niels Giessen
142. Nikolai Weibull
143. Noorul Islam K M
144. Oleh Krehel
145. Paul Sexton
146. Pedro Alexandre Marcelino Costa da Silva
147. Peter Jones
148. Phil Hudson
149. Philip Rooke
150. Phil Jackson
151. Pierre Téchoueyres
152. Pieter Praet
153. Piotr Zielinski
154. Puneeth Chaganti
155. Rafael Laboissière
156. Rainer M Krug
157. Rasmus Pank Roulund
158. Richard Kim
159. Richard Klinda
160. Richard Riley
161. Rick Frankel
162. Robert Michael Irelan
163. Rüdiger Sonderfeld
164. Russel Adams
165. Ryo Takaishi
166. Sacha Chua
167. Samuel Loury
168. Sebastian Miele
169. Sebastian Reuße
170. Sebastian Rose
171. Sebastien Vauban
172. Sergey Litvinov
173. Seweryn Kokot
174. Simon Michael
175. Siraphob Phipathananunth
176. Stardiviner
177. Stephen Eglen
178. Steven Rémot
179. Suvayu Ali
180. Takaaki Ishikawa
181. Tassilo Horn
182. T.F.\nbsp{}Torrey
183. Thibault Marin
184. Thierry Banel
185. Thomas Baumann
186. Thomas Fitzsimmons
187. Thomas Holst
188. Thomas S.\nbsp{}Dye
189. Thorsten Jolitz
190. Tim Burt
191. Tim Landscheidt
192. Titus von der Malsburg
193. Toby Cubitt
194. Tokuya Kameshima
195. Tomas Hlavaty
196. Tom Breton
197. Tom Gillespie
198. Tony Day
199. Toon Claes
200. Trevor Murphy
201. Ulf Stegemann
202. Vitalie Spinu
203. Vladimir Panteleev
204. Yann Hodique
205. Yasushi Shoji
206. Yoshinari Nomura
207. Yuri D.\nbsp{}Lensky
208. Zhang Weize
209. Zhuo Qingliang (Killy Draw)

** Processing

These people have been asked to sign the papers, and they are
currently considering it or a request is being processed by the FSF.

- Brian Carlson [2016-05-24 Tue]
- Bill Wishon
- Mats Kindahl (as of 2013-04-06) for [[http://mid.gmane.org/513BAB7D.1000603@oracle.com][this patch]]
- Georg Lehner (as of 2013-06-27)
- Kodi Arfer (as of 2013-06-29)

** Tiny Changes

These people have submitted tiny change patches that made it into Org
without FSF papers.  When they submit more, we need to get papers
eventually.  The limit is a cumulative change of 20 non-repetitive
change lines.  Details are given in [[http://www.gnu.org/prep/maintain/maintain.html#Legally-Significant ][this document]].

1. Aaron L.\nbsp{}Zeng
2. Abhishek Chandratre
3. Adam Aviv
4. Aliaksey Artamonau
5. Aman Yang
6. Anders Johansson
7. Andrew Burgess
8. Andrew Eggenberger
9. Andrii Kolomoiets
10. Andy Lutomirski
11. Anthony Cowley
12. Anton Latukha
13. Arun Persaud
14. Aurélien Aptel
15. Austin Walker
16. Axel Kielhorn
17. Brad Knotwell
18. Brian Carlson
19. Cheong Yiu Fung
20. Christian Schwarzgruber
21. Chunyang Xu
22. Craig Tanis
23. Daniel Peres Gomez
24. Derek Feichtinger
25. Dima Gerasimov
26. Dominik Schrempf
27. Doro Rose
28. Eduardo Bellani
29. Eric Danan
30. Federico Beffa
31. Feng Zhou
32. Fernando Varesi
33. Florian Beck
34. Francesco Montanari
35. Galen Menzel
36. Georgiy Tugai
37. Gong Qijian
38. Gregor Zattler
39. Greg Tucker-Kellogg
40. Hiroshi Saito
41. Ivan Vilata i Balaguer
42. Jack Henahan
43. Jacob Gerlach
44. Jacob Matthews
45. Jakob Lombacher
46. Jamie Forth
47. Jan Seeger
48. Jason Dunsmore
49. Jason Furtney
50. Jeff Larson
51. Joaquín Aguirrezabalaga
52. Joe Hirn
53. John Foerch
54. John Lee
55. Jonas Hörsch
56. Jon Miller
57. Joost Diepenmaat
58. Jose Robins
59. Kévin Le Gouguec
60. Kodi Arfer
61. Konstantin Kliakhandler
62. Kovacsics Robert
63. Leslie Harlley Watter
64. Leslie Watter
65. Lixin Chin
66. Luke Amdor
67. Marc Ihm
68. Mario Frasca
69. Mario Martelli
70. Marshall Flax
71. Martin Šlouf
72. Martin Vuk
73. Matthew Gidden
74. Matthew MacLean
75. Matt Huszagh
76. Matt Price
77. Max Mouratov
78. Michaël Cadilhac
79. Michael O'Connor
80. Michael Strey
81. Michael Welle
82. Michael Weylandt
83. Mike Ivanov
84. Mike McLean
85. Miro Bezjak
86. Moritz Kiefer
87. Muchenxuan Tong
88. Myles English
89. Myq Larson
90. Nathaniel Nicandro
91. Nick Gunn
92. Nicolò Balzarotti
93. Peter Feigl
94. Peter Moresi
95. Philip (Pip Cet)
96. Piet van Oostrum
97. Renato Ferreira
98. Renato Ferreira
99. Richard Hansen
100. Richard Lawrence
101. Richard Y.\nbsp{}Kim (Kim)
102. Roberto Huelga
103. Robert P.\nbsp{}Goldman
104. Roger Welsh
105. Ruben Maher
106. Sami Airaksinen
107. Saulius Menkevičius
108. Sebastien Le Maguer
109. Sergey Gordienko
110. Sigmund Tzeng
111. Stefano Rodighiero
112. Stefan-W.\nbsp{}Hahn
113. Stig Brautaset
114. Sylvain Chouleur
115. Tadashi Hirata
116. Teika Kazura
117. Terje Larsen
118. Thierry Pellé
119. Thomas Alexander Gerds
120. Thomas Plass
121. Thomas Rikl
122. Tobias Schlemmer
123. Tom Hinton
124. Vicente Vera Parra
125. Viktor Rosenfeld
126. Vladimir Lomov
127. Wojciech Gac
128. Xavier Martinez-Hidalgo
129. Xi Shen
130. York Zhao
131. Yue Zhu
132. Zane D.\nbsp{}Purvis
133. Иван Трусков

(This list may be incomplete - please help completing it.)

** No FSF assignment

These people cannot or prefer to not sign the FSF copyright papers,
and we can only accept patches that do not change the core files (the
ones that are also in Emacs).

Luckily, this list is still empty.

#+BEGIN: timestamp :string "Last update: " :format "%Y-%m-%d @ %H:%M"

#+END: