org-contribute.org

   1 #+OPTIONS:    H:3 num:nil toc:t \n:nil @:t ::t |:t ^:t -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
   2 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
   3 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
   4 #+TAGS:       Write(w) Update(u) Fix(f) Check(c)
   5 #+TITLE:      How to contribute to Org?
   6 #+AUTHOR:     Worg people
   7 #+EMAIL:      bzg AT altern DOT org
   8 #+LANGUAGE:   en
   9 #+PRIORITIES: A C B
  10 #+CATEGORY:   worg
  11
  12 # This file is the default header for new Org files in Worg.  Feel free
  13 # to tailor it to your needs.
  14
  15 [[file:index.org][{Back to Worg's index}]]
  16
  17 * Types of contributions
  18
  19 Every contribution to Org is very welcome.  Here is a list of areas where
  20 your contribution will be useful:
  21
  22 - you can submit *bug reports* -- Before sending a bug report, make sure
  23   you have read this section of Org's manual: [[http://orgmode.org/org.html#Feedback][Feedback]]
  24
  25 - you can submit *feature requests* -- Org is already mature, but new ideas
  26   keep popping up.  If you want to request a feature, it might be a good
  27   idea to have a look at the current [[http://orgmode.org/todo.html][TODO list]] of Org, or to digg into the
  28   mailing list for possible previous discussions about your idea.
  29
  30 - you can submit *patches* -- You can submit patches to the mailing list.
  31
  32   If your patch is against a file that is part of Emacs, then it won't be
  33   taken unless it is /less than 10 lines/ or you granted the rights on your
  34   works to the Free Software Foundation, Inc.
  35
  36   If your patch is against a file that is not part of Emacs, then it might
  37   be taken without worrying about its length, if the patch is good.
  38
  39 - you can submit Org *add-ons* -- there are many Org add-ons.  The best way
  40   is to submit your code to the mailing list to discuss it with people.  If
  41   it is useful, you might consider contributing it to the =CONTRIB/=
  42   directory in the git repository.
  43
  44 - you can submit material to the *Worg* website -- This website is made of
  45   Org files that you can contribute to.  Learn what Worg is [[file:worg-about.org][about]] and how
  46   to contribute to it [[file:worg-git.org][through git]].
  47
  48 * Contributing to Emacs org-mode
  49
  50 Org is made of several files.  Those who are part of GNU Emacs are
  51 copyrighted by the [[http://www.fsf.org][Free Software Foundation, Inc]].  If you consider
  52 contributing to these files, your first need to grant the right to include
  53 your works in GNU Emacs to the FSF.  For this you need to complete [[http://www.cognition.ens.fr/~guerry/u/request-assign-future.txt][this
  54 form]] and send it to [[mailto:assign@gnu.org][assign@gnu.org]].
  55
  56 If you want to understand /why/, please read this: [[http://www.gnu.org/licenses/why-assign.html][Why the FSF gets
  57 copyright assignments from contributors?]]
  58
  59
  60 * Preferred way of submitting patches
  61
  62 Org-mode is developed using /git/ as the version control system.  Git
  63 provides an amazing frame work to collaborate on a project.  Git
  64 can be used to make patches and send them via email - this is fine for
  65 minor changes.  More more significant contributions, the best
  66 way to submit patches is through public branches of your repository
  67 clone.
  68
  69
  70 1. Clone our git repository at =http://repo.or.cz/w/org-mode.git=
  71
  72 2. Create a repository that can be publicly accessed, for example on
  73    /GitHub/, /repo.or.cz/, or on your own server.
  74
  75 3. Push your topic branches (and optionally the master branch) to your
  76    public repository.
  77
  78    Define a remote for your public respository you push topics to.
  79
  80    : git remote add REMOTE URL-GOES-HERE
  81
  82    Push branches to the remote
  83
  84    : git push REMOTE BRANCH1 [BRANCH2 BRANCH3 ...]
  85
  86    e.g.
  87
  88    : git push add github ssh://.../     # Done once to define the remote 'github'
  89    : git push github my-topic
  90
  91 4. Do your work on topic-specific branches, give the branch a name
  92    that relates to what you are working on.
  93
  94 5. Often do
  95
  96    : git remote update
  97
  98    to pull commits from all defined remote repositories, in particular
  99    the org-mode master at /repo.or.cz/.
 100
 101 6. Develop your feature on the topic branch.  It is very helpful if
 102    you can make sure that your branch will merge cleanly into whatever
 103    the current orgigin/master is.  There are two alternative ways to
 104    achieve this:
 105
 106    - *either* test if you branch merges cleanly with
 107
 108       : git checkout -b tmp origin/master^0
 109       : git merge NEWTOPIC
 110       : git checkout master
 111       : git branch -d tmp
 112
 113       If there are conflicts, merge /origin/master/ into your topic branch
 114       and try to resolve the conflicts on your side.
 115
 116    - *or* keep your branch on top of origin/master by regularly using
 117
 118       : git rebase origin/master
 119
 120       to pull all the changes made in origin/mastere _underneath_ our
 121       own changes.
 122
 123 7. When you have something workable, publish the git path and branch
 124    name on the mailing list, so that people can test it and that I can
 125    take a look.
 126
 127 8. When the patch is accepted, I ask you to once again to make sure
 128    that it will cleanly apply.  When that is done, I will fetch your
 129    changes and merge them.  Minor conflicts, such they always arise in
 130    Emacs-style /ChangeLog/ files I can of cause fix while I am doing
 131    the merge.
 132
 133 9. After your topic has been merged to the project master branch you
 134    can delete the topic on your local and remote repositories.
 135
 136    : git branch -d NEWTOPIC
 137    : git push REMOTE :NEWTOPIC
 138
 139
 140
 141 * Current contributors
 142
 143 Here is the list of people who signed the papers with the Free Software
 144 Foundation and can now freely submit code to Org files that are included
 145 within GNU Emacs:
 146
 147 - Konstantin Antipin
 148 - Ian Barton
 149 - Thomas Baumann
 150 - Tom Breton
 151 - Baoqiu Cui
 152 - Sacha Chua
 153 - Dan Davison
 154 - Carsten Dominik
 155 - Miguel A. Figueroa-Villanueva
 156 - Mikael Fornius
 157 - Daniel M German
 158 - Bastien Guerry
 159 - Bernt Hansen
 160 - Tomas Hlavaty
 161 - Tassilo Horn
 162 - Phil Jackson
 163 - Peter Jones
 164 - Tokuya Kameshima
 165 - Christopher League
 166 - Richard Klinda
 167 - Ross Patterson
 168 - Jason Riedy
 169 - Philip Rooke
 170 - Sebastian Rose
 171 - Eric Schulte
 172 - Charles Sebold
 173 - James TD Smith
 174 - Andy Steward
 175 - Christopher Suckling
 176 - David O'Toole
 177 - John Wiegley
 178 - Piotr Zielinski
 179 - James TD Smith
 180
 181 #+BEGIN: timestamp :string "Last update: " :format "%Y-%m-%d @ %H:%M"
 182 Last update: 2008-02-10 @ 16:12
 183 #+END: