About Worg

What is Worg? What is its relation to Org?

Worg is a collaborative knowledge database about Org.

It is made of numerous .org files that you can clone from https://git.sr.ht/~bzg/worg.

Who can participate in the editing of Worg?

Everyone with a minimal knowledge of Org (and Emacs) and git.

You need to register on Sourcehut and ask to be added to the Worg project.

If you are lost, you can ask Timothy for help.

See the section describing How to use git for Worg for details.

Who's in charge of Worg?

Worg is currently maintained by Krupal and Corwin Brust.

Their role is to take care of the Worg repository and to empower new maintainers and contributors.

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

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 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 TODO file will make it easy for everyone to know where he could help.

OK, I want to contribute to Worg now!

First, review How to use git for Worg.

Then, you may be interested in general advice and conventions on how to let Worg grow.

If you're interested in how Worg publishes itself as a website, see the Worg setup page.

Once you are familiar with the above, you can contribute by sending patches against the Worg repository to the 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

The first time you contribute to Worg

Create an account on Sourcehut. Make sure that your public SSH key has been added to your profile.
Request write access to the Worg repo.
Clone the project somewhere in a working directory:
```
~$ git clone git@git.sr.ht:~bzg/worg
```
Go to the newly created worg/ directory and edit some files.
If you created files, add them to the git index:
```
~$ git add *.org
```

Commit changes with the appropriate comment:

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

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

Go to your worg/ directory.
Be sure to "pull" the last version of the repository.
```
~$ git pull --rebase
```
Make some changes. (If you want to learn more about various git workflow, read this page.)

Commit your changes on your local repository:

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

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.
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 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).