~bzg/worg

6ccf3ccff899d235d4258ae3ff630fd42bad0be7 — Greg Minshall 12 days ago 0e553f7
org-contribute.org: Edit and re-organize slightly
1 files changed, 48 insertions(+), 42 deletions(-)

M org-contribute.org
M org-contribute.org => org-contribute.org +48 -42
@@ 19,48 19,54 @@

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 fruits for you and
are willing to help, there is plenty of low-hanging fruit for you, and
the community will welcome your contribution.

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

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

- *Maintain an Org file*: If a file in the git repository does not have
  a maintainer, 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]].
** Ways that do not involve programming

- *Check the [[https://updates.orgmode.org/#help][requests for help]]*: If you want to help with one of these
  tasks, say so on the list.

- *Check the [[https://updates.orgmode.org/#bugs][list of confirmed bugs]]*: Even if you just provide more
  information or ideas on how to fix them, this helps.
- *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 =X-Woof-Bug: confirmed= to your mail headers, and the
  poster and add [[https://github.com/bzg/woof][=X-Woof-Bug: confirmed=]] to your mail headers, and the
  bug will then be shown on [[https://updates.orgmode.org/#bugs][updates.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]].

- *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]].

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

- *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::*How to use git for Worg][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://updates.orgmode.org/#help][requests for help]]*: If you want to help with one of these
  tasks, say so on the list.

- *Check the [[https://updates.orgmode.org/#bugs][list of confirmed bugs]]*: Even if you just provide more
  information or ideas on how to fix them, this helps.

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

- *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


@@ 68,17 74,16 @@ the community will welcome your contribution.
  assignment FSF if you want to add your code in Org's core, because
  it will end up in GNU Emacs.

- *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.
- *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]].

* What does NOT help

- Submitting feature requests without proper justification.
- Submitting "It does not work" bug reports.
- 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.


@@ 97,8 102,8 @@ Contributions are discussed on the [[https://orgmode.org/worg/org-mailing-list.h
  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 is not that
  critical for someone else to confirm it.
  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://updates.orgmode.org][updates.orgmode.org]].  If this is your first patch, don't expect the


@@ 119,8 124,9 @@ 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 *contributor stewards* who will try their best
to make sure your contributions get all the attention they deserve.
The Org mailing list has volunteer *contributor stewards* who will try
their best to make sure your contributions get all the attention they
deserve.

* Your first patch as an occasional contributor
:PROPERTIES:


@@ 139,13 145,11 @@ go through before submitting a patch:
6. If relevant, don't forget to update =doc/org-manual.org=
7. Take extra care of the commit message (see [[#commit-messages][Commit messages and ChangeLog entries]])
8. If your change is small enough and you didn't sign the FSF
   copyright assignment, include =TINYCHANGE= at the bottom of the
   commit message.

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

* Details on how to submit patches
:PROPERTIES:


@@ 160,7 164,7 @@ Lisp coding conventions]] described in Emacs manual.
** Sending patches with Git

Please use Git to make patches and send them via email -- this is
perfectly fine for major and minor changes.
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


@@ 193,13 197,14 @@ To finally send the patches, you can either add them as attachments to
your email 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 (see [[#commit-messages][this
section]] on how to format a ChangeLog entry.)
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 how you can do:
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


@@ 268,6 273,7 @@ A commit message should be constructed in the following way:
  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.