e7d8f124ad
THE BUG - HIGH LEVEL: - When client A sends out an attribute change, client B applies that change to itself but also thinks that it made the change itself, which is incorrect. This means that when client B next makes a change, he will send out that he made the attrib change that A actually made. - Ex: Have 2 clients on the same pad. Have A apply bold on some text. Next, have B type a character. B will broadcast that it both added a character AND applied bold, when in reality it did NOT apply bold at all, that change was done by the other client and this client incorrectly adopted it as its own. - This root bug behavior results in clients continuing to think that they each made the other client's change, thus resulting in an infinite loop of changeset spamming that bogs down clients and harms server stability. THE BUG - IN DEPTH: - The root issue is in the way that Changesets are combined in Changeset.follow(). Specifically, in the case of a changeset with ONLY new attrib changes (no text changes) being merged with an identity changeset (has no ops). - In this case, Changeset.follow() copies the ops of the new CS and fully overrides the other CS. - applyChangesToBase invokes Changeset.follow to determine the final client document CS state after applying the new CS. If the final client document CS state is NOT the identity CS, then the client broadcasts that it made a change. - When client A changes just attribs, client B's applyChangesToBase calls Changeset.follow() and passes client A's changeset (attrib change) and Client B's current changeset state (identity). - As per the noted bug, Changeset.follow() returns client A's changeset as a result, causing client B to adopt client A's changeset as its own document state. Thus, client A ends up thinking it has made client B's changes. THE FIX: - Changeset.follow() should NOT copy the ops of the new CS passed in if those changes are only attrib changes. This allows applyChangesToBase to properly set the client's CS back to the identity after applying an external attrib change, instead of incorrectly adopting the external client's changes. |
||
---|---|---|
bin | ||
doc | ||
src | ||
tests/frontend | ||
tools/doc | ||
var | ||
.gitignore | ||
.travis.yml | ||
CHANGELOG.md | ||
CONTRIBUTING.md | ||
LICENSE | ||
Makefile | ||
README.md | ||
settings.json.template | ||
start.bat |
README.md
A really-real time collaborative word processor for the web
About
Etherpad is a really-real time collaborative editor maintained by the Etherpad Community.
Etherpad is written in Javascript(99.9%) on both the server and client so it's easy for developers to maintain and add new features. Because of this Etherpad has tons of customizations that you can leverage.
Etherpad is designed to be easily embeddable and provides a HTTP API that allows your web application to manage pads, users and groups. It is recommended to use the available client implementations in order to interact with this API.
There is also a jQuery plugin that helps you to embed Pads into your website.
There's also a full-featured plugin framework, allowing you to easily add your own features. By default your Etherpad is rather sparce and because Etherpad takes a lot of it's inspiration from Wordpress plugins are really easy to install and update. Once you have Etherpad installed you should visit the plugin page and take control.
Finally, Etherpad comes with translations into most languages! Users are automatically delivered the correct language for their local settings.
Visit beta.etherpad.org to test it live
Also, check out the FAQ, really!
Installation
Etherpad works with node v0.8 and v0.10, only. (We don't support v0.6)
Windows
Prebuilt windows package
This package works out of the box on any windows machine, but it's not very useful for developing purposes...
- Download the latest windows package
- Extract the folder
Now, run start.bat
and open http://localhost:9001 in your browser. You like it? Next steps.
Fancy install
You'll need node.js and (optionally, though recommended) git.
- Grab the source, either
- download https://github.com/ether/etherpad-lite/zipball/master
- or
git clone https://github.com/ether/etherpad-lite.git
(for this you need git, obviously)
- start
bin\installOnWindows.bat
Now, run start.bat
and open http://localhost:9001 in your browser.
Update to the latest version with git pull origin
, then run bin\installOnWindows.bat
, again.
GNU/Linux and other UNIX-like systems
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"
For FreeBSD: portinstall node node, npm and git (optional)
Additionally, you'll need node.js 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):
- Move to a folder where you want to install Etherpad Lite. Clone the git repository
git clone git://github.com/ether/etherpad-lite.git
- Change into the new directory containing the cloned source code
cd etherpad-lite
Now, run bin/run.sh
and open http://127.0.0.1:9001 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
Tweak the settings
You can initially 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 instances from the same installation.) Once you have access to your /admin section settings can be modified through the web browser.
You should use a dedicated database such as "mysql", if you are planning on using etherpad-in a production environment, since the "dirtyDB" database driver is only for testing and/or development purposes.
Helpful resources
The 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 and watch this video on getting started with Etherpad Development.
If you're new to node.js, start with Ryan Dahl's Introduction to Node.js.
You can debug Etherpad 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 (complex, but worth reading).
Getting started
You know all this and just want to know how you can help?
Look at the TODO list and our Issue tracker. (Please consider using jshint, if you plan to contribute code.)
Also, and most importantly, read our Developer Guidelines, really!
Get in touch
Join the mailinglist and make some noise on our busy freenode irc channel #etherpad-lite-dev!
Modules created for this project
- ueberDB "transforms every database into a object key value store" - manages all database access
- channels "Event channels in node.js" - ensures that ueberDB operations are atomic and in series for each key
- 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
- [Bitcoin] (https://coinbase.com/checkouts/1e572bf8a82e4663499f7f1f66c2d15a)