Updated IRC page for Libera.chat
[worg.git] / worg-about.org
blobb965421bba946912bbdc53f8f743922e0beb3b5b
1 #+TITLE:      About Worg
2 #+AUTHOR:     Worg people
3 #+EMAIL:      mdl AT imapmail DOT org
4 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
5 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
6 #+TAGS:       Write(w) Update(u) Fix(f) Check(c) 
7 #+LANGUAGE:   en
8 #+PRIORITIES: A C B
9 #+CATEGORY:   worg
10 #+OPTIONS:   H:3 num:nil toc:t \n:nil ::t |:t ^:t -:t f:t *:t tex:t d:(HIDE) tags:not-in-toc
11 #+HTML_LINK_UP:    index.html
12 #+HTML_LINK_HOME:  https://orgmode.org/worg/
14 # This file is released by its authors and contributors under the GNU
15 # Free Documentation license v1.3 or later, code examples are released
16 # under the GNU General Public License v3 or later.
18 * Introduction
20 ** What is Worg?  What is its relation to Org?
22 [[http://www.orgmode.org][Org]] is an [[http://www.gnu.org/software/emacs/][Emacs]] mode for /keeping notes, maintaining to-do lists, and
23 doing project planning with a fast and effective plain-text system/
24 (as the [[http://www.orgmode.org/org.html][Org manual]] says).
26 Worg is a /collectively/-built knowledge database about [[https://orgmode.org][Org]],
27 planning in plain text, and other related topics.
29 ** Why use Org-mode for creating a collaborative website?
31 Because Org makes it easy, fast and effective to edit *well-structured*
32 files.  Ever wanted to edit a [[file:org-tutorials/tables.org][table]] in a wiki?  Ever wanted to change the
33 outline structure in a wikipage?  Ever wanted to edit lists quickly?  Org
34 lets you do this.
36 Because Org-mode makes *beautiful* documents: it supports links, font
37 beautification, examples, etc.  And you can export those documents to
38 HTML, LaTeX, or DocBook.
40 Because Org is also a powerful *task-management system*.  Hopefully sharing
41 a [[file:todo.org][TODO file]] will make it easy for everyone to know where he could help.
43 ** So Worg is a bit like a wiki, no?
45 No.  Yes.  Kind of.  Here are a few differences:
47 - you edit the pages *using Emacs*, not a cheesy web interface;
49 - the Worg website (repository) is maintained using [[http://git-scm.com/][git]];
51 - even if people are invited to merge their changes into the [[https://orgmode.org/worg/][main Worg
52   website]], they are free to start a new Worgie of their own.  Using git
53   makes Worg a *distributed* community website.
55 - there is an important difference: Org is a very fast and effective plain
56   text task-management system.  Meaning that you can add the Worg todo
57   file (=todo.org= in the Worg directory) to your =org-agenda-files= and
58   see your list of task populated by tasks added by other people...
60 ** So what is contained in Worg?
62 Everything related to Org, project planning in plain text, and the Org
63 community.  Go crazy!
65 * Who can participate in the editing of Worg?
67 Everyone with a minimal knowledge of Org (and Emacs) and git.  See the
68 section describing [[*How to use git for Worg][How to use git for Worg]] for details.
70 * Do I need to register somewhere?
72 You just need to send your requested username to [[mailto:tec@tecosaur.com][Timothy]], he will
73 create an account on [[https://code.orgmode.org][code.orgmode.org]] for you --- see [[*How to use git for Worg][How to use git for Worg]] for more information.
75 * Who's in charge of Worg?
77 Worg was started by [[http://bzg.fr][Bastien]] in the hope that other Org-ers around will
78 bite into this and start sharing tutorials, example of codes, etc.
80 Worg is currently maintained by Krupal and Corwin Brust.
82 Their role is to take care of [[https://code.orgmode.org/bzg/worg/][the Worg repository]] and to empower new
83 maintainers and contributors.
85 * OK, I want to *contribute to Worg* now!
87 The first thing you need to know is review [[*How to use git for Worg][How to use git for Worg]].
89 The second thing you might be interested in is general advice and
90 conventions on how to [[file:worg-editing.org][let Worg grow]].
92 If you're interested in knowing how Worg publishes itself as a website,
93 check the [[file:worg-setup.org][Worg setup]] page.
95 If or once you are familiar with the above, you can contribute by sending patches against the Worg repository to
96 the [[file:org-mailing-list.org][Org mailing list]].
98 : ~$ git clone https://code.orgmode.org/bzg/worg.git
100 If you want to contribute regularily, you can ask for commit access.
101 When you get it, you can clone the repository like this:
103 : ~$ git clone git@code.orgmode.org:bzg/worg.git
105 and push commits directly.
107 ** How to use git for Worg
109 *** What is git?
111 [[http://git.or.cz][git]] is a fast version control system that lets you collaborate on a
112 project.  For details on how to use git, go and read the [[http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html][git tutorial]].
113 For details on the public git repository, please check it [[https://code.orgmode.org/bzg/worg][here]].
115 The homepage of the Worg project is here: https://orgmode.org/worg/.
117 To clone a read-only copy of the repo:
119    : ~$ git clone https://code.orgmode.org/bzg/worg.git
121 If you intend to push changes, see below to ask for an account; and,
122 then clone like this:
124    : ~$ git clone git@code.orgmode.org:bzg/worg.git
126 Since Worg is constantly updated you may want to update your copy of
127 Worg before reading sometimes later.  To do so =cd= into the Worg
128 directory and upgrade your copy of Worg with the command:
130    : ~$ git pull
132 If you want to contribute to Worg, keep reading.
134 *** The first time you contribute to Worg
135   :PROPERTIES:
136   :CUSTOM_ID: contribute-to-worg
137   :END:
139 1. If you don't have a SSH-key, [[file:worg-git-ssh-key.org][create one]].
141 2. Create an account on https://code.orgmode.org by emailing your
142    requested username to [[mailto:tec@tecosaur.com][Timothy]].
144 3. Add your public key on this account.
146 4. Install =git= on your system. Tell =git= to use your private key with
147    worg by updating =~/.ssh/config= with:
149      : Host code.orgmode.org
150      :      HostName code.orgmode.org
151      :      IdentityFile ~/.ssh/your-private-ssh-key-file-name
153 5. Clone the project somewhere in a working directory:
155      : ~$ git clone git@code.orgmode.org:bzg/worg.git
157 6. Go to the newly created =worg/= directory and edit some files.
159 7. If you created files, add them to the git index:
161    : ~$ git add *.org
163 8. Commit changes with the appropriate comment:
165    : ~$ git commit -a -m "summary comment about all changes"
167 9. Ask =bzg AT gnu.org= to be added as a collaborator on the Worg repo.
169 10. When you are a collaborator, push your change to Worg:
171       : ~$ git push
173     The system is designed for immediate updates -- if not, it means
174     something is wrong.  You should be able to read the error message
175     and see what is wrong, then help with fixing issues.  In general
176     the issues are trivial to fix.
178 *** The second time you contribute to Worg
180 1. Go to your =worg/= directory.
182 2. Be sure to "pull" the last version of the repository.
184   : ~$ git pull --rebase
186 3. Make some changes.  (If you want to learn more about various git
187    workflow, read [[file:worg-git-advanced.org][this page]].)
189 4. Commit your changes on your local repository:
191    : ~$ git commit -a -m "summary comment about all changes"
193 5. Push your change on the remote repository
195    : ~$ git push
197 *** Going deeper
199 **** Getting organized
201 The Worg TODO file is =todo.org=.  If you are a Worg zealot, maybe
202 you want to add this file to the list of your agenda files.  For
203 example, here is my =org-agenda-files= variable:
205   : (setq org-agenda-files '("~/org/bzg.org" "~/git/worg/todo.org")
207 I have an agenda custom command for checking tasks that are assigned
208 to me:
210   : (org-add-agenda-custom-command '("W" tags "Owner=\"Bastien\""))
212 The next time someone assigns a task for me, it will appear in my Worg
213 agenda view.
215 **** Register your changes under your name
217 Information regarding your name can be stored in your global
218 =~/.gitconfig= file, or in =Worg/.git/config=.
220 Edit it like this:
222 : [user]
223 :        name = FirstName LastName
224 :        email = you@yourdomain.example.com
226 Now your changes will be filed under your name.
228 # I'm not sure this is useful at all:
230 **** Rebase to avoid merging commits
232 It's good practice to pull the current version of the repository
233 before making your own additions. But even if you do, someone might
234 make a change while you are working. So it will often be necessary to
235 pull immediately before pushing your new commit. In this situation, if
236 you use =git pull= directly, then a 'merge commit' will be generated,
237 looking like this:
239 #+begin_example
240 commit aaaabbbbbbbbbaaaaaaaaabbbbbbbb
241 Merge: bababa efefefef
242 Author: Some one <name@domain>
243 Date:   Wed Nov 24 00:00:01 2010 -0700
245     Merge branch 'master' of git@code.orgmode.org:bzg/worg.git
246 #+end_example
248 That's not a major problem, but it's nice to keep the commit logs free
249 of this stuff. To avoid generating the merge commit, use the =--rebase=
250 option when pulling:
252 : ~$ git pull --rebase
254 Basically this means that your commit will be put to the top of the
255 stack, as if no one had made any additions while you were
256 working. More advanced git users might make their changes in a
257 personal branch, and then rebase that branch against a freshly pulled
258 master branch before merging it in to master. The end result would be
259 the same as pulling with =--rebase=.
261 **** Dealing with line endings
263 Unix, Windows and Mac all have different conventions for marking the
264 end of a line. This might lead to problems when editing the same file
265 across platforms. Github advises Linux users to automatically convert
266 all external files to LF on committing (see
267 [[http://help.github.com/dealing-with-lineendings]]) by setting:
269 : ~$ git config --global core.autocrlf input
271 For Worg, this is the wrong solution, since there are already files
272 with both end of line conventions in the repository.  Instead tell git
273 locally not to convert files by setting:
275 : ~$ git config core.autocrlf false
277 Of course you have to be careful not to save Windows files as Unix
278 files or vice versa, since this would lead to large and confusing
279 diffs. This should not be a problem with Worg as
281 - one rarely edits other people's files anyway, and
282 - Emacs can deal with end of line conventions transparently.
284 **** Git usage for people who just want to send patches
286 See [[file:worg-git-advanced.org][this page]].
288 **** Emacs' in-built version control system and git
290    Emacs's VC supports many common git operations, but others, like
291    repository syncing must be done from the command line.  For example
292    the Command =C-x v v= does check in changes in the *local* and not
293    in the *remote* repository in contrast to other back ends like svn.
294    It is necessary to do additionally
296 : ~$ git push
298    to sync the change on the remote server.
300 ** Something went wrong
302 *** Preventing publishing errors
304 Locally export any document you edit as HTML (=C-c C-e h H=) prior to
305 committing it to Worg and ensure the export process doesn't fail.
306 This will be more reliable if you're running the latest version of
307 Org.
309 You may also want to check the formatting in a browser before
310 committing your change (=C-c C-e h o=).
312 *** Troubleshooting publishing errors
314 If you notice Worg isn't updating, visit [[https://orgmode.org/worg/publishing.txt][publishing.txt]] and look for
315 the export error near the bottom to find the file where publishing
316 stopped.  Locally update to the latest version of Org, open that file,
317 and try reproducing the export error (=C-c C-e h H=).  If it's not
318 obvious where the problem is, look at the most recent changes to the
319 file in question:
321 : cd Worg
322 : git log -p org-quotes.org
324 Try reverting some of those changes and then re-test exporting (=C-c
325 C-e h H=).