#+TITLE:      Contributing to Org
#+AUTHOR:     Worg people
#+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
#+HTML_LINK_UP:    index.html
#+HTML_LINK_HOME:  https://orgmode.org/worg/

# This file is released by its authors and contributors under the GNU
# Free Documentation license v1.3 or later, code examples are released
# under the GNU General Public License v3 or later.

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

#+begin_highlightbox
You do not need to be proficient in programming to contribute to Org
mode.  You are even allowed to make mistakes ;) Just drop us an email
(no mailing list subscription required) with your idea (or asking for
an idea) and we will guide you along.
#+end_highlightbox

The Org codebase is large, and contributing can be daunting at first,
but don't hesitate to call for directions on [[file:org-mailing-list.org][the mailing list]].  If you
are willing to help, there is plenty of low-hanging fruit for you, and
the community will welcome your contribution.

You can also contact some Org maintainers directly [[file:org-maintenance.org::#web-presense-maintainers][on Reddit, GitHub,
IRC, Matrix or other platforms]] if it is easier. However, we prefer the
mailing list, if possible.

Alternatively, you may drop in to our monthly [[file:orgmeetup.org][OrgMeetup]] and talk to
the maintainers and other users in real time. Even better, join
[[file:orgdevmeetup.org][OrgDevMeetup]] and try contributing to Org directly, under guidance from
actual devs.

Sometimes, emails to the mailing list are not answered. Either due to
lack of time or simply because things fall through the cracks. If there
is no answer for over a month, do no hesitate to follow up. See
https://orgmode.org/worg/org-mailing-list.html#i-didnt-receive-an-answer

* Overview of Org repositories
:PROPERTIES:
:CUSTOM_ID: repos-overview
:END:

- [[https://git.savannah.nongnu.org/cgit/org-mode.git][Org repository on Savannah]]: =git clone https://https.git.savannah.nongnu.org/git/org-mode.git= (or use mirror =git clone https://git.sr.ht/~bzg/org-mode=)
- [[https://sr.ht/~bzg/org][Org project on SourceHut]] with other repositories: [[https://git.sr.ht/~bzg/worg][worg]] and [[https://git.sr.ht/~bzg/orgweb][orgweb]]
- [[file:org-orphanage.org][Org orphanage]] lists orphan Org libraries in search for maintainers
- [[https://git.sr.ht/~bzg/org-contrib][org-contrib]] (aka the old =contrib/= dir) also contains libraries in search for maintainers.

* Ways to contribute 🦄
:PROPERTIES:
:CUSTOM_ID: types-of-contributions
:END:

** Ways that do not involve programming

- *Send bug reports*.  Before sending a bug report, make sure you read
  the section of the manual on how to provide useful [[https://orgmode.org/org.html#Feedback][feedback]] or this
  other great text: [[http://www.chiark.greenend.org.uk/~sgtatham/bugs.html][How to Send Bug Reports Effectively]].

- *Try to reproduce bugs*: That's always very helpful.  Do subscribe to
  [[https://lists.gnu.org/mailman/listinfo/emacs-orgmode][Org's mailing list]] and monitor new unreferenced bugs.  Try to
  reproduce them.  If you can reproduce a bug, reply to the original
  poster and add [[https://tracker.orgmode.org/howto][=Confirmed.=]] in a separate line of your email text,
  and the bug will then be shown on [[https://tracker.orgmode.org/?types=bug][tracker.orgmode.org]].

- *Help other users by replying to their questions* [[file:org-mailing-list.org][on the mailing list]]
  or on [[file:org-web-social.org][other web places]].

- *Join the liaison team* by committing to reply to 1-2 email
  submissions per week on the mailing list. You can help us making
  sure that all the bug reports get the attention they deserve and are
  not left without response. More details on [[file:org-maintenance.org::#liaison][maintenance page]].

  #+begin_warningbox
  We currently have enough volunteers to cover the incoming
  reports. If you are interested in small fixed-time commitment, drop
  an email to the list, and we can arrange regular small tasks to work
  on.
  #+end_warningbox
  
- *Contribute to Worg*.  Worg is collaborative documentation made of Org
  files.  It's very easy to contribute to it.  Learn more [[file:worg-about.org][about Worg]]
  and [[file:worg-about.org::#git][how to contribute]].

- *Share ideas and feature requests*.  Org is already mature, but new
  ideas keep popping up.  If you want to request a feature, first dig
  into [[file:org-mailing-list.org][the mailing list]] to find similar proposals.  If you cannot find
  any, subscribe to the list, read it for a while, then make your
  proposal.  Formulate it with as much detail as possible, especially
  with examples.

** Ways that involve programming

- *Check the [[https://tracker.orgmode.org/requests?sorting-by=date][requests for help]]*: If you want to help with one of these
  tasks, say so on the list.

- *Check the [[https://tracker.orgmode.org/bugs?sorting-by=date][list of confirmed bugs]]*: Even if you just provide more
  information or ideas on how to fix them, this helps.  More detailed
  instructions [[#fixbug][below]].

- *Review patches* submitted by others: Take a look at the [[https://tracker.orgmode.org/?types=patch][list of
  patches]]. You can always help by checking the patch against [[#patches][our
  conventions]], by running =make test=, or by trying out the patch
  yourself and attempting to break it :) Also, check out [[#patch-review][more detailed instructions]].

- *Join the liaison team* by committing to reply to 1-2 email
  submissions per week on the mailing list. You can help us making
  sure that all the bug reports and patches get the attention they
  deserve and are not left without response. More details on
  [[file:org-maintenance.org::#liaison][maintenance page]].

  #+begin_warningbox
  We currently have enough volunteers to cover the incoming
  reports. If you are interested in small fixed-time commitment, drop
  an email to the list, and we can arrange regular small tasks to work
  on.
  #+end_warningbox

- *Submit patches* to the mailing list.  See how to format [[#first-patch][your first
  patch]] and [[#patches][details on how to submit it]].

  - If you have problems with patch workflow, you may also share a
    link to your public git repository containing changes or submit
    the changed files directly

- *Write add-ons*.  The best way is to submit your code to [[file:org-mailing-list.org][the mailing
  list]] and discuss it with people.  Many add-ons are published through
  [[https://elpa.gnu.org/][GNU ELPA]] (for authors who signed the FSF copyright assignment) and
  [[https://elpa.nongnu.org/][NonGNU ELPA]] (for others).  You'll need to sign the FSF copyright
  assignment FSF if you want to add your code in Org's core, because
  it will end up in GNU Emacs.

  - [[https://orgmode.org/worg/org-tutorials/melpa-github.html][Step-by-step guide how to write and publish an add-on from scratch]]

- *Maintain an Org file*: If a file in the git repository does not
  have a maintainer [fn:: =grep -lv "^;; Maintainer:" `find ./lisp
  -name "*.el"` | less=] and you want to help by maintaining it,
  please read more on [[file:org-maintenance.org][how Org is maintained]] and let us know by sending
  an email to [[file:org-mailing-list.org][the mailing list]].

  Maintaining a library usually requires \approx{}1 hour per week commitment.
  \approx{}1 hour per month for smaller libraries.

  List of Org libraries in a search for maintainers:
  # Auto-generate the list of unmaintainerd libraries
  #+begin_src emacs-lisp :eval yes :exports results :results raw value :var org-git-path="~/org-mode/"
  (let* ((org-git-lisp-path
  	(file-name-as-directory
           (file-name-concat (expand-file-name org-git-path) "lisp")))
         (files (directory-files-recursively org-git-lisp-path "\\.el$"))
         output)
    (thread-last
      (shell-command-to-string
       (format "grep -L \"^;; Maintainer:\" %s"
  	     (mapconcat #'identity files " ")))
      (replace-regexp-in-string (regexp-quote org-git-lisp-path) "")
      (split-string)
      (delete "org-version.el")
      (delete "org-loaddefs.el")
      (mapconcat (lambda (s) (format "=%s=, " s)))
      (replace-regexp-in-string ", $" "")
      (replace-regexp-in-string "^$" "<none>")))
  #+end_src

  In the absence of dedicated maintainers taking care about these
  libraries, the official Org mode project maintainer has to be in
  charge. But there is only that much a single person can do.

* What does NOT help

- Submitting feature requests without proper justification.
- Submitting [[https://www.chiark.greenend.org.uk/~sgtatham/bugs.html]["It does not work"]] bug reports.
- Submitting ill-formatted patches.
- Sending too many emails.
- Arguing.

We follow the [[https://www.gnu.org/philosophy/kind-communication.html][GNU Kind Communications Guidelines]] and ask you to follow
them too.

* As a contributor, what can I expect?
:PROPERTIES:
:CUSTOM_ID: what-can-I-expect
:END:

Contributions are discussed on the [[https://orgmode.org/worg/org-mailing-list.html][Org mailing list]].

- When you contribute with a bug report :: Expect someone to try
  reproducing the bug.  Please make it easier by providing a minimal
  reproducible recipe.  Check the manual on how to provide [[https://orgmode.org/manual/Feedback.html][feedback]].
  If no one replies, don't take it personally: it either means that
  nobody was able to reproduce the bug or that the bug does not seem
  that critical for someone else to confirm it.

- When you contribute with a patch :: Your patch will be listed on
  [[https://tracker.orgmode.org/patches][tracker.orgmode.org]].  If this is your first patch, don't expect the
  patch to be applied immediately.  You can expect someone to review
  it and to suggest changes, either on the technical or formal aspects
  of the patch.  If nobody seems to care enough to reply, don't take
  it personally: it means that maintainers are busy and/or that the
  patch does not seem critical enough.

- When you contribute with an idea or a feature request ::  The best
  way to convince maintainers that your idea is worth considering is
  by detailing your use-case and by proposing a patch for it.  Expect
  people to discuss the idea on the list, but please remember Org is
  very old now, used by many people with various needs.  If nobody
  replies, don't take it personally.

  : When contributing, always keep the maintenance burden in mind:
  : are you alleviating it, or are you adding to it?

In general, if you want to raise awareness on an email you sent,
please wait at least for *one month* before bumping a thread.  See [[file:org-mailing-list.org::#i-didnt-receive-an-answer][What
to do if you don't receive an answer]].

The Org mailing list has volunteer *liaison team* who will try their
best to make sure your contributions get all the attention they
deserve.

* How to fix a bug
:PROPERTIES:
:CUSTOM_ID: fixbug
:END:

Once you identified a bug you want to fix (either from [[file:org-mailing-list.org][the mailing
list]] or from [[https://tracker.orgmode.org][BARK tracker]]), you can go ahead and try fixing it.

Here are the basic steps how to do it:

1. Try to reproduce it locally
   - first, with your normal Emacs config
   - it that does not work, try =make repro= from Org mode git
     repository (see [[https://orgmode.org/manual/Feedback.html#Feedback][Feedback section]] in Org mode manual)
2. If the bug is not reproducible, inform the person who reported
   the bug, and ask for additional details that might be missing
   in the original report. In most cases, asking to follow [[https://orgmode.org/manual/Feedback.html#Feedback][Feedback
   section]] in Org mode manual can lead to a good reproducible recipe.
3. Find which part of Org code is causing the problem.  You can use
   =edebug=, =M-x debug-on-entry=, modifying the code with ~(message
   ...)~, or ~(debug)~ statements directly - remember that you can
   re-define functions on the fly in Elisp. (See more details in
   [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Debugging.html][Debugging Lisp Programs]]).
4. Even if you cannot fix the bug yourself, providing your findings to
   the mailing list is already helpful.
5. Try to fix it by modifying Org mode sources
   - remember that you can ask for more guidance on the mailing list
6. [[#first-patch][Submit a patch]] with your fixes (ideally, replying in the same
   thread where the bug is reported)

* Your first patch as an occasional contributor
:PROPERTIES:
:CUSTOM_ID: first-patch
:END:

You don't need write access to the repository to contribute with
patches, just send them to [[file:org-mailing-list.org][the mailing list]].  Here is a checklist to
go through before submitting a patch:
  
1. Make your patch against the latest =bugfix= or =main= branch
2. Run =~$ make test= to catch broken tests[fn:: If the patch is trivial enough, testing against your own version of GNU Emacs is probably enough. For new features and complex changes, we recommend testing against the latest stable version of GNU Emacs.]
4. Check compilation warnings with =~$ make compile=
5. If relevant, include or update tests
6. If your patch is adding a feature, please update =etc/ORG-NEWS=
7. If relevant, don't forget to update =doc/org-manual.org=
8. Take extra care of the commit message (see [[#commit-messages][Commit messages and ChangeLog entries]]).
   You can optionally install =~$ make githooks= to auto-check for most common issues.
9. If your change is small enough and you didn't sign the FSF copyright assignment[fn:: 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][copyright]] of your contribution to the Free Software Foundation.], include =TINYCHANGE= at the bottom of the commit message.

* If creating a patch is difficult, a simple diff will also do

1. Download Org mode source code from command line:

   : git clone https://https.git.savannah.nongnu.org/git/org-mode.git
   : # or use mirror
   : git clone https://git.sr.ht/~bzg/org-mode

   This will create "org-mode" folder in the place you run the above
   command.

2. Open the Org library you want to modify in the downloaded folder

3. Edit the file as needed

4. =M-x vc-diff <RET>=

   This will open a buffer with you edits converted into "diff"

5. =C-x C-w= (=M-x write-file=) in the diff buffer and save it to a
   file like =my-edits.diff=

6. Drop an email to mailto:emacs-orgmode@gnu.org, explaining what you
   did and attaching the "diff" file

* Details on how to submit 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.

On top of these conventions :

- When creating an option (as =defcustom=) or changing the default value
  of an existing one, use the next stable version of Org as the value
  of =package-version=.  E.g. if the main branch version is =9.6-pre=, use
  =9.6= for =package-version=.

- Do not create commits that only perform space replacements [fn::
  Whitespace-only commits make it difficult to search across git
  history.  See the discussion in
  https://yhetil.org/emacs-devel/E1k8aul-0001mr-Mg@fencepost.gnu.org/].

- When writing comments, docstrings, and function/variable names,
  please use American English.  This is GNU Emacs convention we
  follow.  See [[https://cgit.git.savannah.gnu.org/cgit/emacs.git/tree/CONTRIBUTE#n139][CONTRIBUTE file]] in GNU Emacs repository.

** Sending patches with Git

Please use Git or [[https://magit.vc/][Magit]] to make patches and send them via email --
this is perfectly fine for both major and minor changes.

When sending a patch (using =git diff=, =git format-patch= or =git
send-email=, *always add a properly formatted Emacs ChangeLog entry* in
the commit message.  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= or =git
send-email=.  Here is a suggested workflow:

#+begin_quote
:   ~$ git pull                 # make sure your repo is up to date
:   ~$ git branch my-changes    # create a new branch from main
:   ~$ 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 main                 # Creates two patches (.patch files)

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

To finally send the patches, you can either add them as attachments to
your email (easier) or use [[https://git-scm.com/docs/git-send-email][git send-email]], if it's properly
configured.

Write useful commit messages: please provide (1) a reason for it in
your email and (2) a ChangeLog entry in the commit message (again, 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 what 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/main=):

  : git diff -p origin/main 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

When discussing important changes, it is sometimes not so useful to
send long and/or numerous patches.

In this case, you can maintain your changes on a public branch of a
public clone of Org and send a link to the diff between your changes
and the latest Org commit that sits in your clone.

If the discussion settles and your change is accepted, you can now
send it as (a list of) patch(es) to the latest Org version.

* Your first commit as an Org maintainer
:PROPERTIES:
:CUSTOM_ID: devs
:END:

Org regular contributors and file maintainers have write access to the
[[https://git.savannah.nongnu.org/cgit/org-mode.git/][Git repository]].

1. Fill in [[https://orgmode.org/request-assign-future.txt][this form]] and wait for the FSF feedback
2. Create an account on [[https://savannah.gnu.org][savannah.gnu.org]]
3. Request to join the [[https://savannah.nongnu.org/projects/org-mode][Savannah Org mode group]]

Once you are granted access to the Org mode group:

1. If your change is backward-incompatible, discuss it first on the list
2. Apply your changes against the code and the documentation
3. Run =make test=
4. Remember to add a "news" entry in the =etc/ORG-NEWS= file if needed
5. If the tests pass, commit and push your changes

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

To check our Git workflow in more details, please read [[file:org-maintenance.org][Org maintenance]].

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

** What's in a commit message?

A commit message is a plain text message accompanying the code changes
in the patch/commit.  Its purpose is describing the changes made and
their motivation.  When sending patches with =git send-email=, the
commit message will be in the email body.  When the patch is created
via =git format-patch=, the commit message will be included into the
patch file itself.

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, like this:
  : lisp/ol-man.el: Restore file

- Line 2 is an empty line.

- Line 3 starts the ChangeLog entry.  It looks like [[https://git.savannah.nongnu.org/cgit/org-mode.git/commit/?id=d49957ef021e256f19092c907d127390d39ec1ed][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.

  There should be an entry for /every/ file changed in the commit.  This
  includes, for instance, =etc/ORG-NEWS= and =doc/org-manual.org= if your
  change was relevant there.  [[https://git.savannah.nongnu.org/cgit/org-mode.git/commit/?id=bea9fca18][This]] is a good example of a =TINYCHANGE=
  that also touched the manual and news files.

  Please refer to [[https://www.gnu.org/prep/standards/html_node/Change-Logs.html#Change-Logs][GNU standards]] for more detailed information about
  the purpose and contents of the ChangeLog entries.

- After the ChangeLog entry, 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= after the ChangeLog entry.

- If the commit fixes a bug reported by someone on the list, you can
  add this contextual information like this:

  : Reported-by: "Bruce E. Robertson" <brucer42@gmail.com>
  : Link: https://list.orgmode.org/877dch89s1.fsf@kyleam.com/

  Only add links to the mailing list archive at
  https://list.orgmode.org.

  If a bug has been reported elsewhere on the web, don't reference
  such URLs: send an email to the list with a bug report and add a
  reference to your email in the commit message.

** The logic behind commit message structure

- When you look at the git log, you will see only the first line of the
  commit message.  So, git log should be written in such a way that a
  person just skimming through the first lines could get an idea about
  what kind of changes have been done.  For example, take a look at
  [[https://git.savannah.nongnu.org/cgit/org-mode.git/log/]]
  You should be able to tell, without looking into actual changes, what
  happened to Org mode repository recently.

  If you split similar changes into multiple commits, they will not
  provide useful information - you will just introduce consequent
  (almost) identical lines into the log.

  For the same reason, putting very different changes into a single
  commit message is not useful.  There is only that much you can fit
  into the first line.  If you do not describe all the changes in the
  first line, they may be missed while reading the log.

  An analogy of the first line of a commit message is title of a
  video/article/blog post.  It is the first thing the reader
  encounters, and it should indicate whether more detailed reading is
  needed.

- At the second level we have the rest of the commit message.  This is
  a kind of abstract summarizing changes.  One should be able to
  understand what kind of changes were done and why they were done, in
  plain English.  That's why (and for [[https://www.gnu.org/prep/standards/html_node/Change-Logs.html#Change-Logs][historical reasons]]) it follows
  ChangeLog format were each changed function/section should be
  annotated.

  Any links in the commit message should be permanent, if at all
  possible.  Commit messages are written once and will not be changed,
  so any supporting link should remain accessible for as long as
  possible.  Otherwise, future readers may not be able to understand
  the context in full.

** Conventions

- Variables and functions names are quoted wither like ='this'= (two
  single quotes) or like =`this'= (a backquote and a single
  quote). The latter is the convention used in Elisp docstrings.

- 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".

** Example

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

** Git Hooks
:PROPERTIES:
:CUSTOM_ID: git-hooks
:END:

The Org repository has a set of git hook scripts that can be used to
perform validation on commit messages and structure. If you would like
to utilize these scripts, you can link the existing files under the
~git-hooks~ directory into the ~.git/hooks~ subdirectory. If you
want to use all of the hooks, there is a Makefile target that does
this for you:

#+begin_src shell
make githooks
#+end_src

If you would like to remove the hooks, simply delete them from
~.git/hooks~ or run the Makefile target (~cleanall~ will also run this):

#+begin_src shell
make cleangithooks
#+end_src

** Producing ChangeLog entries

If you are using [[https://magit.vc/][magit]] in Emacs, the ChangeLog for such entries can be
produced by pressing =C= (for ~magit-commit-add-log~) on the diff chunks
of a staged file.  (If you prefer storing your ChangeLog entries in a
file, you can also use =C-x 4 a=
(~magit-add-change-log-entry-other-window~) from within magit display of
diff chunks.)

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

Further reference:

- [[https://www.gnu.org/prep/standards/html_node/Style-of-Change-Logs.html#Style-of-Change-Logs][Standard Emacs change log entry format]]
- [[http://git.savannah.gnu.org/cgit/emacs.git/plain/CONTRIBUTE][Contribution guide from Emacs repo]]

* How to review a patch
:PROPERTIES:
:CUSTOM_ID: patch-review
:END:

We regularly receive new patches on [[file:org-mailing-list.org][the mailing list]]. They are
automatically listed on [[https://tracker.orgmode.org][BARK tracker]], and the [[https://tracker.orgmode.org/reports/patches-open.xml][tracker's RSS feed]].

Reviewing a patch involves a number of steps, varying depending on
its complexity. Some steps are easy - anyone, even people with
limited programming experience, can perform part of the review.

Providing even a partial review already helps - patch submitter
will see interest in their contributions; the maintainers will
need less time to complete the full review; and, indeed, the reviewer
can potentially learn along the way.

When reporting issues, be constructive: describe what you observed,
suggest alternatives if possible, and reference the relevant checklist
item.

#+begin_highlightbox
Before pointing out deficiencies in a contribution, be sure to include
your positive thoughts on the contribution.  The submitter has spent
the time to create, format, and send this contribution.  Especially
for new contributors, this can be a lot of effort.  They went through
this effort in an attempt to improve their own lives, as well as the
lives of others.  It can be very difficult to discern mood and tone
through email which means it is very easy to accidentally discourage
people.  A simple "What you've done here is very helpful and I'm glad
you helped us" can mean a lot to some people.
#+end_highlightbox

Below is the detailed checklist for reviewing patches:

** Beginner-friendly review steps

These checks can be performed by anyone familiar with Org's basic
usage and do not require deep Elisp knowledge.

1. Is the patch accompanied by an explanation why it is needed?  If
   not, it is a good idea to ask for one.

2. Does the patch introduce anything that can potentially break
   existing user workflows? If yes, try to come up with alternative
   approach and suggest to the patch author. (Just pointing to
   potential problem also helps, but it is much nicer to also suggest
   an alternative).

3. If a patch is introducing a new feature, can some existing feature
   be extended (reasonably) to fit the same purpose?  If yes, it is
   often better to extend something existing. Org mode users are
   already exposed to huge number of workflows, so we generally prefer
   to fit new things into the existing paradigms rather than
   introducing something completely new.

4. Is every single change in the patch annotated by corresponding
   changelog entry in the commit message? If not, it often means that
   the change is an unrelated slip-in. You can kindly request the
   submitter to provide the missing annotations.

5. Are the changelog entries conforming with [[#commit-messages][our conventions]]?  If not,
   it is usually trivial to fix the issues.

6. Can the patch apply to the latest version of Org mode?  If not, it
   should probably be updated.  Here, you can use [[https://docs.magit.vc/magit/Applying.html][Magit]], [[https://docs.kyleam.com/piem/Applying-patches-contained-in-a-message.html][Piem]], or Git
   itself (e.g., =git apply --check= to test, =git am= to apply).

7. If the patch does apply, does it also pass all the Org mode tests
   (=make test=)?  Does it compile without warnings (=make compile=)?
   If not, the patch must be fixed.

8. If the patch does apply, does it do the job it's supposed to
   according to its description? Are there any edge cases that might
   not work correctly? At this point, it is a good idea to try running
   Emacs and Org mode with the patch applied and attempting to perform
   actions that are affected by the patch. If something is broken, you
   can share the findings with the patch author, similar to [[#types-of-contributions][how bugs
   are reported]] for the Org mode itself.

9. Does the code style in the patch conform to [[#patches][the coding conventions]]?
   An easy way to check about conventions is looking at the code
   around where the patch makes changes. The style (functions used,
   indentation, variable names, etc) should look similar.

10. If the patch introduces new functions or variables, do they all
    come with a docstring? If yes, is that docstring conforming to the
    [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tips.html][Elisp documentation conventions]]?

11. Does the patch break any of the existing Org features?  Breaking
    the features described in the [[https://orgmode.org/manual/][Org manual]] is generally not
    tolerated without strong justification.

12. If the patch is introducing a new feature or changing the existing
    one, is it accompanied by new tests? Are the changes recorded in
    =etc/ORG-NEWS= file? Maybe it is also worth describing in the Org
    manual?

13. If the patch is documenting new commands or variables in the
    manual, are the proper index entries also added?

14. Does the patch work with all the supported Emacs versions (the last
    three stable Emacs releases)?

** Advanced review steps

These require understanding of Org's internal design, user
expectations, and long-term maintenance tradeoffs.

1. Does the patch code implement its intended purpose explained in the
   commit message and/or email? Are there any edge cases in the
   specific implementation? May it be broken in some scenarios? This
   step is what most people call code review, especially when a patch
   is about adding new functions or libraries.

2. Is there any chance that changes break the logic flow of functions
   that are affected by the patch? You can read through the functions
   before vs. after the patch being applied and think of potential
   broken logic. For example, some functions may maintain internal
   assumptions about the state of let-bound variables. New changes
   sometimes break those, causing collateral breakage.

3. Does the patch potentially break some Org conventions that are not
   explicitly described in the manual, but are still present? If yes,
   is there a chance that some Org users may be implicitly relying on
   these undocumented features? You can quickly check source code of
   Org-related packages on ELPA and other websites to see if they rely
   on those conventions. This is a tricky step that requires good
   understanding of both internal logic and how users are using Org
   mode.

4. If the patch is introducing major changes, do the changes fit
   within general logic of Org mode operation? Does it break [[https://orgmode.org/worg/org-maintenance.html#guidelines][general
   principles]]? May it be at the odds how things in the [[https://orgmode.org/manual/][Org manual]] are
   introduced? If the patch is using unusual code design, can we
   instead re-use the principles we already have in the codebase?

5. If the patch is introducing a new Org library, does it have a proper
   library header that explains the library purpose, preferably with
   some examples?

6. Is the patch exceeding 15 lines of code? If yes, and the author is
   not in [[https://orgmode.org/worg/contributors.html][the list of contributors with FSF assignment]], either ask the
   Org mode maintainer (who has access to the official list on the GNU
   servers) or the patch author about the copyright status. You can
   link to [[#copyright][relevant section below]] in your response.

* Dealing with copyright when contributing to Org mode
:PROPERTIES:
:CUSTOM_ID: copyright
:END:

All Elisp Org files are also distributed as part of GNU Emacs, they
are all copyrighted by the [[http://www.fsf.org][Free Software Foundation, Inc]].

If you consider contributing to these files, your 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 to 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.

If you want to learn more about /why/ copyright assignments are
collected, read these: [[http://www.gnu.org/licenses/why-assign.html][Why the FSF gets copyright assignments from
contributors?]], [[https://sfconservancy.org/blog/2021/jun/30/who-should-own-foss-copyrights/][It Matters Who Owns Your Copylefted Copyrights]].

By submitting patches to =emacs-orgmode@gnu.org= or by pushing changes
to Org's core files, 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.  

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

You can check current contributors on [[file:contributors.org][this page]].