diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b0fff543e..4a69a3b65 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,9 @@ # Developer Guidelines (Please talk to people on the mailing list before you change this page, see our section on [how to get in touch](https://github.com/ether/etherpad-lite#get-in-touch)) +## Important note for pull requests +**Pull requests should issued against the develop branch**. We never pull directly into master. + **Our goal is to iterate in small steps. Release often, release early. Evolution instead of a revolution** ## General goals of Etherpad Lite diff --git a/README.md b/README.md new file mode 100644 index 000000000..71ce8e77a --- /dev/null +++ b/README.md @@ -0,0 +1,126 @@ +# Making collaborative editing the standard on the web + +# About +Etherpad lite is a really-real time collaborative editor spawned from the Hell fire of Etherpad. +We're reusing the well tested Etherpad easysync library to make it really realtime. Etherpad Lite +is based on node.js ergo is much lighter and more stable than the original Etherpad. Our hope +is that this will encourage more users to use and install a realtime collaborative editor. A smaller, manageable and well +documented codebase makes it easier for developers to improve the code and contribute towards the project. + +**Etherpad vs Etherpad lite** + + + + + + + + + + + + + + + + +
 EtherpadEtherpad Lite
Size of the folder (without git history)30 MB1.5 MB
Languages used server sideJavascript (Rhino), Java, ScalaJavascript (node.js)
Lines of server side Javascript code~101k~9k
RAM Usage immediately after start257 MB (grows to ~1GB)16 MB (grows to ~30MB)
+ + +Etherpad Lite is designed to be easily embeddable and provides a [HTTP API](https://github.com/ether/etherpad-lite/wiki/HTTP-API) +that allows your web application to manage pads, users and groups. It is recommended to use the client implementations available for this API, listed on [this wiki page](https://github.com/ether/etherpad-lite/wiki/HTTP-API-client-libraries). +There is also a [jQuery plugin](https://github.com/johnyma22/etherpad-lite-jquery-plugin) that helps you to embed Pads into your website + +**Visit [beta.etherpad.org](http://beta.etherpad.org) to test it live** + +Also, check out the **[FAQ](https://github.com/ether/etherpad-lite/wiki/FAQ)**, really! + +# Installation + +## Windows + +### Prebuilt windows package +This package works out of the box on any windows machine, but it's not very useful for developing purposes... + +1. Download the windows package +2. Extract the folder + +Now, run `start.bat` and open in your browser. You like it? [Next steps](#next-steps). + +### Fancy install +You'll need [node.js](http://nodejs.org) and (optionally, though recommended) git. + +1. Grab the source, either + - download + - or `git clone https://github.com/ether/etherpad-lite.git` (for this you need git, obviously) +2. start `bin\installOnWindows.bat` + +Now, run `start.bat` and open in your browser. + +Update to the latest version with `git pull origin`, then run `bin\installOnWindows.bat`, again. + +[Next steps](#next-steps). + +## Linux +You'll need gzip, git, curl, libssl develop libraries, python and gcc. +*For Debian/Ubuntu*: `apt-get install gzip git-core curl python libssl-dev pkg-config build-essential` +*For Fedora/CentOS*: `yum install gzip git-core curl python openssl-devel && yum groupinstall "Development Tools"` + +Additionally, you'll need [node.js](http://nodejs.org) installed, Ideally the latest stable version, be careful of installing nodejs from apt. + +**As any user (we recommend creating a separate user called etherpad-lite):** + +1. Move to a folder where you want to install Etherpad Lite. Clone the git repository `git clone git://github.com/ether/etherpad-lite.git` +2. Change into the new directory containing the cloned source code `cd etherpad-lite` + +Now, run `bin/run.sh` and open in your browser. + +Update to the latest version with `git pull origin`. The next start with bin/run.sh will update the dependencies. + +You like it? [Next steps](#next-steps). + +# Next Steps + +## Tweak the settings +You can modify the settings in `settings.json`. (If you need to handle multiple settings files, you can pass the path to a settings file to `bin/run.sh` using the `-s|--settings` option. This allows you to run multiple Etherpad Lite instances from the same installation.) + +You should use a dedicated database such as "mysql", if you are planning on using etherpad-lite in a production environment, since the "dirtyDB" database driver is only for testing and/or development purposes. + +## Helpful resources +The [wiki](https://github.com/ether/etherpad-lite/wiki) is your one-stop resource for Tutorials and How-to's, really check it out! Also, feel free to improve these wiki pages. + +Documentation can be found in `docs/`. + +# Development + +## Things you should know +Read this [git guide](http://learn.github.com/p/intro.html) and watch this [video on getting started with Etherpad Lite Development](http://youtu.be/67-Q26YH97E). + +If you're new to node.js, start with Ryan Dahl's [Introduction to Node.js](http://youtu.be/jo_B4LTHi3I). + +You can debug Etherpad lite using `bin/debugRun.sh`. + +If you want to find out how Etherpad's `Easysync` works (the library that makes it really realtime), start with this [PDF](https://github.com/ether/etherpad-lite/raw/master/doc/easysync/easysync-full-description.pdf) (complex, but worth reading). + +## Getting started +You know all this and just want to know how you can help? + +Look at the [TODO list](https://github.com/ether/etherpad-lite/wiki/TODO) and our [Issue tracker](https://github.com/ether/etherpad-lite/issues). (Please consider using [jshint](http://www.jshint.com/about/), if you plan to contribute code.) + +Also, and most importantly, read our [**Developer Guidelines**](https://github.com/ether/etherpad-lite/wiki/Developer-Guidelines), really! + +# Get in touch +Join the [mailinglist](http://groups.google.com/group/etherpad-lite-dev) and make some noise on our freenode irc channel [#etherpad-lite-dev](http://webchat.freenode.net?channels=#etherpad-lite-dev)! + +# Modules created for this project + +* [ueberDB](https://github.com/ether/ueberDB) "transforms every database into a object key value store" - manages all database access +* [channels](https://github.com/ether/channels) "Event channels in node.js" - ensures that ueberDB operations are atomic and in series for each key +* [async-stacktrace](https://github.com/ether/async-stacktrace) "Improves node.js stacktraces and makes it easier to handle errors" + +# Donate! +* [Flattr] (http://flattr.com/thing/71378/Etherpad-Foundation) +* Paypal - Press the donate button on [etherpad.org](http://etherpad.org) + +# License +[Apache License v2](http://www.apache.org/licenses/LICENSE-2.0.html)