Merge remote-tracking branch 'srht/master'

[worg.git] / worg-about.org

#+TITLE:      About Worg
#+AUTHOR:     Worg people
#+EMAIL:      mdl AT imapmail DOT org
#+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
#+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
#+TAGS:       Write(w) Update(u) Fix(f) Check(c) 
#+LANGUAGE:   en
#+PRIORITIES: A C B
#+CATEGORY:   worg
#+OPTIONS:   H:3 num:nil toc:t \n:nil ::t |:t ^:t -:t f:t *:t tex:t d:(HIDE) tags:not-in-toc
#+HTML_LINK_UP:    index.html
#+HTML_LINK_HOME:  https://orgmode.org/worg/

# This file is released by its authors and contributors under the GNU
# Free Documentation license v1.3 or later, code examples are released
# under the GNU General Public License v3 or later.

* Introduction

** What is Worg?  What is its relation to Org?

[[http://www.orgmode.org][Org]] is an [[http://www.gnu.org/software/emacs/][Emacs]] mode for /keeping notes, maintaining to-do lists, and
doing project planning with a fast and effective plain-text system/
(as the [[http://www.orgmode.org/org.html][Org manual]] says).

Worg is a /collectively/-built knowledge database about [[https://orgmode.org][Org]],
planning in plain text, and other related topics.

** Why use Org-mode for creating a collaborative website?

Because Org makes it easy, fast and effective to edit *well-structured*
files.  Ever wanted to edit a [[file:org-tutorials/tables.org][table]] in a wiki?  Ever wanted to change the
outline structure in a wikipage?  Ever wanted to edit lists quickly?  Org
lets you do this.

Because Org-mode makes *beautiful* documents: it supports links, font
beautification, examples, etc.  And you can export those documents to
HTML, LaTeX, or DocBook.

Because Org is also a powerful *task-management system*.  Hopefully sharing
a [[file:todo.org][TODO file]] will make it easy for everyone to know where he could help.

** So Worg is a bit like a wiki, no?

No.  Yes.  Kind of.  Here are a few differences:

- you edit the pages *using Emacs*, not a cheesy web interface;

- the Worg website (repository) is maintained using [[http://git-scm.com/][git]];

- even if people are invited to merge their changes into the [[https://orgmode.org/worg/][main Worg
  website]], they are free to start a new Worgie of their own.  Using git
  makes Worg a *distributed* community website.

- there is an important difference: Org is a very fast and effective plain
  text task-management system.  Meaning that you can add the Worg todo
  file (=todo.org= in the Worg directory) to your =org-agenda-files= and
  see your list of task populated by tasks added by other people...

** So what is contained in Worg?

Everything related to Org, project planning in plain text, and the Org
community.  Go crazy!

* Who can participate in the editing of Worg?

Everyone with a minimal knowledge of Org (and Emacs) and git.  See the
section describing [[*How to use git for Worg][How to use git for Worg]] for details.

* Do I need to register somewhere?

You need to register on [[https://sr.ht][Sourcehut]] and ask to be added to the [[https://git.sr.ht/~bzg/worg][Worg
project]].

If you are lost, you can ask [[mailto:tec@tecosaur.com][Timothy]] for help.  See also, [[*How to use git for Worg][How to use
git for Worg]].

* Who's in charge of Worg?

Worg was started by [[http://bzg.fr][Bastien]] in the hope that other Org-ers around will
bite into this and start sharing tutorials, example of codes, etc.

Worg is currently maintained by Krupal and Corwin Brust.

Their role is to take care of [[https://git.sr.ht/~bzg/worg][the Worg repository]] and to empower new
maintainers and contributors.

* OK, I want to *contribute to Worg* now!

First, review [[*How to use git for Worg][How to use git for Worg]].

Then, you may be interested in general advice and conventions on how
to [[file:worg-editing.org][let Worg grow]].

If you're interested in how Worg publishes itself as a website, see
the [[file:worg-setup.org][Worg setup]] page.

Once you are familiar with the above, you can contribute by sending
patches against the Worg repository to the [[file:org-mailing-list.org][Org mailing list]].

: ~$ git clone https://git.sr.ht/~bzg/worg

If you want to contribute regularly, you can ask for commit access.
When you get it, you can clone the repository like this:

: ~$ git clone git@git.sr.ht:~bzg/worg

and push commits directly.

** How to use git for Worg

*** What is git?

[[http://git.or.cz][git]] is a fast version control system that lets you collaborate on a
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]].
For details on the public git repository, please check it [[https://git.sr.ht/~bzg/worg][here]].

The homepage of the Worg project is here: https://orgmode.org/worg/.

To clone a read-only copy of the repo:

   : ~$ git clone https://git.sr.ht/~bzg/worg

If you intend to push changes, see below to ask for an account; and,
then clone like this:

   : ~$ git clone git@git.sr.ht:~bzg/worg

Since Worg is constantly updated you may want to update your copy of
Worg before reading sometimes later.  To do so =cd= into the Worg
directory and upgrade your copy of Worg with the command:

   : ~$ git pull

If you want to contribute to Worg, keep reading.

*** The first time you contribute to Worg
  :PROPERTIES:
  :CUSTOM_ID: contribute-to-worg
  :END:

1. Create an account on [[https://sr.ht][Sourcehut]].

2. Request write access to [[https://git.sr.ht/~bzg/worg][the Worg repo]].

3. Clone the project somewhere in a working directory:

     : ~$ git clone git@git.sr.ht:~bzg/worg

4. Go to the newly created =worg/= directory and edit some files.

5. If you created files, add them to the git index:

   : ~$ git add *.org

6. Commit changes with the appropriate comment:

   : ~$ git commit -a -m "summary comment about all changes"

7. When you are a collaborator, push your change to Worg:

     : ~$ git push

   The system is designed for immediate updates -- if not, it means
   something is wrong.  You should be able to read the error message
   and see what is wrong, then help with fixing issues.  In general
   the issues are trivial to fix.

*** The second time you contribute to Worg

1. Go to your =worg/= directory.

2. Be sure to "pull" the last version of the repository.

  : ~$ git pull --rebase

3. Make some changes.  (If you want to learn more about various git
   workflow, read [[file:worg-git-advanced.org][this page]].)

4. Commit your changes on your local repository:

   : ~$ git commit -a -m "summary comment about all changes"

5. Push your change on the remote repository

   : ~$ git push

*** Going deeper

**** Getting organized

The Worg TODO file is =todo.org=.  If you are a Worg zealot, maybe
you want to add this file to the list of your agenda files.  For
example, here is my =org-agenda-files= variable:

  : (setq org-agenda-files '("~/org/bzg.org" "~/git/worg/todo.org")

I have an agenda custom command for checking tasks that are assigned
to me:

  : (org-add-agenda-custom-command '("W" tags "Owner=\"Bastien\""))

The next time someone assigns a task for me, it will appear in my Worg
agenda view.

**** Register your changes under your name

Information regarding your name can be stored in your global
=~/.gitconfig= file, or in =Worg/.git/config=.

Edit it like this:

: [user]
:        name = FirstName LastName
:        email = you@yourdomain.example.com

Now your changes will be filed under your name.

# I'm not sure this is useful at all:

**** Rebase to avoid merging commits

It's good practice to pull the current version of the repository
before making your own additions. But even if you do, someone might
make a change while you are working. So it will often be necessary to
pull immediately before pushing your new commit. In this situation, if
you use =git pull= directly, then a 'merge commit' will be generated,
looking like this:

#+begin_example
commit aaaabbbbbbbbbaaaaaaaaabbbbbbbb
Merge: bababa efefefef
Author: Some one <name@domain>
Date:   Wed Nov 24 00:00:01 2010 -0700

    Merge branch 'master' of git@git.sr.ht:~bzg/worg
#+end_example

That's not a major problem, but it's nice to keep the commit logs free
of this stuff. To avoid generating the merge commit, use the =--rebase=
option when pulling:

: ~$ git pull --rebase

Basically this means that your commit will be put to the top of the
stack, as if no one had made any additions while you were
working. More advanced git users might make their changes in a
personal branch, and then rebase that branch against a freshly pulled
master branch before merging it in to master. The end result would be
the same as pulling with =--rebase=.

**** Dealing with line endings

Unix, Windows and Mac all have different conventions for marking the
end of a line. This might lead to problems when editing the same file
across platforms. Github advises Linux users to automatically convert
all external files to LF on committing (see
[[http://help.github.com/dealing-with-lineendings]]) by setting:

: ~$ git config --global core.autocrlf input

For Worg, this is the wrong solution, since there are already files
with both end of line conventions in the repository.  Instead tell git
locally not to convert files by setting:

: ~$ git config core.autocrlf false

Of course you have to be careful not to save Windows files as Unix
files or vice versa, since this would lead to large and confusing
diffs. This should not be a problem with Worg as

- one rarely edits other people's files anyway, and
- Emacs can deal with end of line conventions transparently.

**** Git usage for people who just want to send patches

See [[file:worg-git-advanced.org][this page]].

**** Emacs' in-built version control system and git

   Emacs's VC supports many common git operations, but others, like
   repository syncing must be done from the command line.  For example
   the Command =C-x v v= does check in changes in the *local* and not
   in the *remote* repository in contrast to other back ends like svn.
   It is necessary to do additionally

: ~$ git push

   to sync the change on the remote server.

** Something went wrong

*** Preventing publishing errors

Locally export any document you edit as HTML (=C-c C-e h H=) prior to
committing it to Worg and ensure the export process doesn't fail.
This will be more reliable if you're running the latest version of
Org.

You may also want to check the formatting in a browser before
committing your change (=C-c C-e h o=).

*** Troubleshooting publishing errors

If you notice Worg isn't updating, visit [[https://orgmode.org/worg/publishing.txt][publishing.txt]] and look for
the export error near the bottom to find the file where publishing
stopped.  Locally update to the latest version of Org, open that file,
and try reproducing the export error (=C-c C-e h H=).  If it's not
obvious where the problem is, look at the most recent changes to the
file in question:

: cd Worg
: git log -p org-quotes.org

Try reverting some of those changes and then re-test exporting (=C-c
C-e h H=).