From 8cf98908c94c2f8bbc0abcfc5cf948dc0a0820e3 Mon Sep 17 00:00:00 2001 From: Greg Minshall Date: Fri, 8 Oct 2021 15:08:17 +0300 Subject: [PATCH 2/2] org-contribute.org: Edit and re-organize slightly --- org-contribute.org | 90 ++++++++++++++++++++++++---------------------- 1 file changed, 48 insertions(+), 42 deletions(-) diff --git a/org-contribute.org b/org-contribute.org index a21c5223..d684ccdb 100644 --- a/org-contribute.org +++ b/org-contribute.org @@ -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. -- 2.32.0