Browse Source

Be more specific on how to edit the manuals

Bastien 1 year ago
parent
commit
cac75f5499
1 changed files with 51 additions and 45 deletions
  1. 51 45
      org-contribute.org

+ 51 - 45
org-contribute.org

@@ -22,11 +22,26 @@
 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 *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 *feature requests* -- Org is already mature, but new
+- 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
@@ -35,35 +50,19 @@ where your contribution will be useful:
   possible, if possible with examples, and send it to the mailing
   list.
 
-- 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 Org *add-ons* -- there are many Org add-ons.
+- 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
+    [[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.
 
-- 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]].
-
 * Copyright issues when contributing to Emacs Org mode
 :PROPERTIES:
 :CUSTOM_ID: copyright-issues
@@ -95,10 +94,10 @@ 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.
+;; 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
@@ -107,35 +106,42 @@ 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.
+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:
 
-1. Create an account on https://code.orgmode.org
-
-2. Add your public key to the account
+** Git branches
 
-3. Ask [[mailto:bzgATgnuDOTorg][Bastien]] to be added as a collaborator on the repository
+Please read [[https://code.orgmode.org/bzg/org-mode/src/master/README_maintainer][README_maintainer]] file within Org's repository.
 
-4. Clone =org-mode.git= repository like this:
-
-   : ~$ git clone git@code.orgmode.org:bzg/org-mode.git
-
-5. Commit your changes.
+** 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
-for them.
+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: