Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Reformat README.*.md to 70 characters uniformly. 

There are some stragglers, but this is better than the previous SOTW
where line length was all over the place.
This commit is contained in:
Luke Faraone 2016-03-21 03:40:10 +00:00
parent cd2348e9ae
commit d93a2bcf11
2 changed files with 134 additions and 76 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

152
README.dev.md
View File

@ -27,8 +27,7 @@ such as Mac via Virtualbox (but everything will be 2-3x slower).
``` ```
* If your host is Ubuntu 14.04, you will need to [download a newer * If your host is Ubuntu 14.04, you will need to [download a newer
version of Vagrant](https://www.vagrantup.com/downloads.html), and version of Vagrant][vagrant-dl], and then do the following:
then do the following:
``` ```
sudo apt-get install lxc lxc-templates cgroup-lite redir sudo apt-get install lxc lxc-templates cgroup-lite redir
sudo dpkg -i vagrant*.deb # in directory where you downloaded vagrant sudo dpkg -i vagrant*.deb # in directory where you downloaded vagrant
@ -36,12 +35,11 @@ such as Mac via Virtualbox (but everything will be 2-3x slower).
``` ```
* For other Linux hosts with a kernel above 3.12, [follow the Vagrant * For other Linux hosts with a kernel above 3.12, [follow the Vagrant
LXC installation LXC installation instructions][vagrant-lxc] to get Vagrant with LXC
instructions](https://github.com/fgrehm/vagrant-lxc) to get Vagrant for your platform.
with LXC for your platform.
* If your host is OS X or older Linux, [download VirtualBox](https://www.virtualbox.org/wiki/Downloads), * If your host is OS X or older Linux, [download VirtualBox][vbox-dl],
[download Vagrant](https://www.vagrantup.com/downloads.html), and install them both. [download Vagrant][vagrant-dl], and install them both.
* If you're on OS X and have VMWare, it should be possible to patch * If you're on OS X and have VMWare, it should be possible to patch
Vagrantfile to use the VMWare vagrant provider which should perform Vagrantfile to use the VMWare vagrant provider which should perform
@ -54,6 +52,10 @@ such as Mac via Virtualbox (but everything will be 2-3x slower).
core.autocrlf=false` to avoid Windows line endings being added to core.autocrlf=false` to avoid Windows line endings being added to
files (this causes weird errors). files (this causes weird errors).
[vagrant-dl]: https://www.vagrantup.com/downloads.html
[vagrant-lxc]: https://github.com/fgrehm/vagrant-lxc
[vbox-dl]: https://www.virtualbox.org/wiki/Downloads
Once that's done, simply change to your zulip directory and run Once that's done, simply change to your zulip directory and run
`vagrant up` in your terminal to install the development server. This `vagrant up` in your terminal to install the development server. This
will take a long time on the first run because Vagrant needs to will take a long time on the first run because Vagrant needs to
@ -74,12 +76,16 @@ source /srv/zulip-venv/bin/activate
To get shell access to the virtual machine running the server to run To get shell access to the virtual machine running the server to run
lint, management commands, etc., use `vagrant ssh`. lint, management commands, etc., use `vagrant ssh`.
(A small note on tools/run-dev.py: the `--interface=''` option will make (A small note on tools/run-dev.py: the `--interface=''` option will
the development server listen on all network interfaces. While this make the development server listen on all network interfaces. While
is correct for the Vagrant guest sitting behind a NAT, you probably this is correct for the Vagrant guest sitting behind a NAT, you
don't want to use that option when using run-dev.py in other environments). probably don't want to use that option when using run-dev.py in other
environments).
At this point you should [read about using the development environment](https://github.com/zulip/zulip/blob/master/README.dev.md#using-the-development-environment). At this point you should [read about using the development
environment][using-dev].
[using-dev]: #using-the-development-environment
Using provision.py without Vagrant Using provision.py without Vagrant
@ -123,7 +129,11 @@ Install the following non-Python dependencies:
### On Debian or Ubuntu systems: ### On Debian or Ubuntu systems:
``` ```
sudo apt-get install closure-compiler libfreetype6-dev libffi-dev memcached rabbitmq-server libldap2-dev redis-server postgresql-server-dev-all libmemcached-dev python-dev hunspell-en-us nodejs nodejs-legacy npm git yui-compressor puppet gettext sudo apt-get install closure-compiler libfreetype6-dev libffi-dev \
memcached rabbitmq-server libldap2-dev redis-server \
postgresql-server-dev-all libmemcached-dev python-dev \
hunspell-en-us nodejs nodejs-legacy npm git yui-compressor \
puppet gettext
# If on 12.04 or wheezy: # If on 12.04 or wheezy:
sudo apt-get install postgresql-9.1 sudo apt-get install postgresql-9.1
@ -145,21 +155,26 @@ Now continue with the "All systems" instructions below.
### On Fedora 22 (experimental): ### On Fedora 22 (experimental):
These instructions are experimental and may have bugs; patches welcome! These instructions are experimental and may have bugs; patches
welcome!
``` ```
sudo dnf install libffi-devel memcached rabbitmq-server openldap-devel python-devel redis postgresql-server postgresql-devel postgresql libmemcached-devel freetype-devel nodejs npm yuicompressor closure-compiler gettext sudo dnf install libffi-devel memcached rabbitmq-server \
openldap-devel python-devel redis postgresql-server \
postgresql-devel postgresql libmemcached-devel freetype-devel \
nodejs npm yuicompressor closure-compiler gettext
``` ```
Now continue with the Common to Fedora/CentOS instructions below. Now continue with the Common to Fedora/CentOS instructions below.
### On CentOS 7 Core (experimental): ### On CentOS 7 Core (experimental):
These instructions are experimental and may have bugs; patches welcome! These instructions are experimental and may have bugs; patches
welcome!
``` ```
# Add user zulip to the system (not necessary if you configured zulip as the administrator # Add user zulip to the system (not necessary if you configured zulip
# user during the install process of CentOS 7). # as the administrator user during the install process of CentOS 7).
useradd zulip useradd zulip
# Create a password for zulip user # Create a password for zulip user
@ -173,13 +188,16 @@ zulip ALL=(ALL) ALL
# Switch to zulip user # Switch to zulip user
su zulip su zulip
# Enable EPEL 7 repo so we can install rabbitmq-server, redis and other dependencies # Enable EPEL 7 repo so we can install rabbitmq-server, redis and
# other dependencies
sudo yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm sudo yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
# Install dependencies # Install dependencies
sudo yum install libffi-devel memcached rabbitmq-server openldap-devel python-devel redis postgresql-server \ sudo yum install libffi-devel memcached rabbitmq-server openldap-devel
postgresql-devel postgresql libmemcached-devel wget python-pip openssl-devel freetype-devel libjpeg-turbo-devel \ python-devel redis postgresql-server postgresql-devel postgresql \
zlib-devel nodejs yuicompressor closure-compiler gettext libmemcached-devel wget python-pip openssl-devel freetype-devel \
libjpeg-turbo-devel zlib-devel nodejs yuicompressor \
closure-compiler gettext
# We need these packages to compile tsearch-extras # We need these packages to compile tsearch-extras
sudo yum groupinstall "Development Tools" sudo yum groupinstall "Development Tools"
@ -206,17 +224,21 @@ Now continue with the Common to Fedora/CentOS instructions below.
### On OpenBSD 5.8 (experimental): ### On OpenBSD 5.8 (experimental):
These instructions are experimental and may have bugs; patches welcome! These instructions are experimental and may have bugs; patches
welcome!
``` ```
doas pkg_add sudo bash gcc postgresql-server redis rabbitmq memcached node libmemcached py-Pillow py-cryptography py-cffi doas pkg_add sudo bash gcc postgresql-server redis rabbitmq \
memcached node libmemcached py-Pillow py-cryptography py-cffi
# Get tsearch_extras and build it (using a modified version which aliases int4 on OpenBSD): # Get tsearch_extras and build it (using a modified version which
# aliases int4 on OpenBSD):
git clone https://github.com/blablacio/tsearch_extras git clone https://github.com/blablacio/tsearch_extras
cd tsearch_extras cd tsearch_extras
gmake && sudo gmake install gmake && sudo gmake install
# Point environment to custom include locations and use newer GCC (needed for Node modules): # Point environment to custom include locations and use newer GCC
# (needed for Node modules):
export CFLAGS="-I/usr/local/include -I/usr/local/include/sasl" export CFLAGS="-I/usr/local/include -I/usr/local/include/sasl"
export CXX=eg++ export CXX=eg++
@ -224,8 +246,9 @@ export CXX=eg++
sudo mkdir /usr/local/share/postgresql/tsearch_data sudo mkdir /usr/local/share/postgresql/tsearch_data
# Hack around missing dictionary files -- need to fix this to get # Hack around missing dictionary files -- need to fix this to get the
# the proper dictionaries from what in debian is the hunspell-en-us package. # proper dictionaries from what in debian is the hunspell-en-us
# package.
sudo touch /usr/local/share/postgresql/tsearch_data/english.stop sudo touch /usr/local/share/postgresql/tsearch_data/english.stop
sudo touch /usr/local/share/postgresql/tsearch_data/en_us.dict sudo touch /usr/local/share/postgresql/tsearch_data/en_us.dict
sudo touch /usr/local/share/postgresql/tsearch_data/en_us.affix sudo touch /usr/local/share/postgresql/tsearch_data/en_us.affix
@ -243,8 +266,9 @@ cd ts2
make make
sudo make install sudo make install
# Hack around missing dictionary files -- need to fix this to get # Hack around missing dictionary files -- need to fix this to get the
# the proper dictionaries from what in debian is the hunspell-en-us package. # proper dictionaries from what in debian is the hunspell-en-us
# package.
sudo touch /usr/share/pgsql/tsearch_data/english.stop sudo touch /usr/share/pgsql/tsearch_data/english.stop
sudo touch /usr/share/pgsql/tsearch_data/en_us.dict sudo touch /usr/share/pgsql/tsearch_data/en_us.dict
sudo touch /usr/share/pgsql/tsearch_data/en_us.affix sudo touch /usr/share/pgsql/tsearch_data/en_us.affix
@ -252,7 +276,8 @@ sudo touch /usr/share/pgsql/tsearch_data/en_us.affix
# Edit the postgres settings: # Edit the postgres settings:
sudo vi /var/lib/pgsql/data/pg_hba.conf sudo vi /var/lib/pgsql/data/pg_hba.conf
# Add this line before the first uncommented line to enable password auth: # Add this line before the first uncommented line to enable password
# auth:
host all all 127.0.0.1/32 md5 host all all 127.0.0.1/32 md5
# Start the services # Start the services
@ -291,14 +316,20 @@ To start the development server:
Using Docker Using Docker
------------- -------------
You can also use Docker to develop, first you need to install Docker in your development machine following the [instructions](https://docs.docker.com/engine/installation/). Some other interesting links for somebody new in Docker are: You can also use Docker to develop, first you need to install Docker
in your development machine following the
[instructions][docker-install].
Some other interesting links for somebody new in Docker are:
* [Get Started](https://docs.docker.com/linux/started/) * [Get Started](https://docs.docker.com/linux/started/)
* [Understand the architecture](https://docs.docker.com/engine/introduction/understanding-docker/) * [Understand the architecture](https://docs.docker.com/engine/introduction/understanding-docker/)
* [Docker run reference](https://docs.docker.com/engine/reference/run/) * [Docker run reference](https://docs.docker.com/engine/reference/run/)
* [Dockerfile reference](https://docs.docker.com/engine/reference/builder/) * [Dockerfile reference](https://docs.docker.com/engine/reference/builder/)
Then you should create the Docker image based on Ubuntu Linux, first go to the directory with the Zulip source code: [docker-install]: https://docs.docker.com/engine/installation/
Then you should create the Docker image based on Ubuntu Linux, first
go to the directory with the Zulip source code:
``` ```
docker build -t user/zulipdev . docker build -t user/zulipdev .
@ -316,10 +347,12 @@ docker commit -m "Zulip installed" <container id> user/zulipdev:v2
Finally you can run the docker server with: Finally you can run the docker server with:
``` ```
docker run -itv $(pwd):/srv/zulip -p 80:9991 user/zulipdev:v2 /srv/zulip/scripts/start-dockers docker run -itv $(pwd):/srv/zulip -p 80:9991 user/zulipdev:v2 \
/srv/zulip/scripts/start-dockers
``` ```
If you want to connect to the Docker instance to build a release tarball you can use: If you want to connect to the Docker instance to build a release
tarball you can use:
``` ```
docker ps docker ps
@ -335,14 +368,16 @@ docker ps
docker kill <container id> docker kill <container id>
``` ```
If you want to run all the tests you need to start the servers first, you can do it with: If you want to run all the tests you need to start the servers first,
you can do it with:
``` ```
docker run -itv $(pwd):/srv/zulip user/zulipdev:v2 /bin/bash docker run -itv $(pwd):/srv/zulip user/zulipdev:v2 /bin/bash
$ scripts/test-all-docker $ scripts/test-all-docker
``` ```
You can modify the source code in your development machine and review the results in your browser. You can modify the source code in your development machine and review
the results in your browser.
Using the Development Environment Using the Development Environment
@ -370,10 +405,10 @@ browser window to see changes take effect.
* If you change Python code used by the the main Django/Tornado server * If you change Python code used by the the main Django/Tornado server
processes, these services are run on top of Django's [manage.py processes, these services are run on top of Django's [manage.py
runserver](https://docs.djangoproject.com/en/1.8/ref/django-admin/#runserver-port-or-address-port), runserver][django-runserver] which will automatically restart the
which will automatically restart the Zulip Django and Tornado servers Zulip Django and Tornado servers whenever you save changes to Python
whenever you save changes to Python code. You can watch this happen code. You can watch this happen in the `run-dev.py` console to make
in the `run-dev.py` console to make sure the backend has reloaded. sure the backend has reloaded.
* The Python queue workers don't automatically restart when you save * The Python queue workers don't automatically restart when you save
changes (or when they stop running), so you will want to ctrl-C and changes (or when they stop running), so you will want to ctrl-C and
@ -382,29 +417,34 @@ queue workers or if a queue worker has crashed.
* If you change the database schema, you'll need to use the standard * If you change the database schema, you'll need to use the standard
Django migrations process to create and then run your migrations; see Django migrations process to create and then run your migrations; see
the [new feature the [new feature tutorial][new-feature-tutorial] for an example.
tutorial](http://zulip.readthedocs.org/en/latest/new-feature-tutorial.html) Additionally you should check out the [detailed testing
for an example. Additionally you should check out the [detailed docs][testing-docs] for how to run the tests properly after doing a
testing docs](http://zulip.readthedocs.org/en/latest/testing.html) for migration.
how to run the tests properly after doing a migration.
(In production, everything runs under supervisord and thus will (In production, everything runs under supervisord and thus will
restart if it crashes, and `upgrade-zulip` will take care of running restart if it crashes, and `upgrade-zulip` will take care of running
migrations and then cleanly restaring the server for you). migrations and then cleanly restaring the server for you).
[django-runserver]: https://docs.djangoproject.com/en/1.8/ref/django-admin/#runserver-port-or-address-port
[new-feature-tutorial]: http://zulip.readthedocs.org/en/latest/new-feature-tutorial.html
[testing-docs]: http://zulip.readthedocs.org/en/latest/testing.html
Running the test suite Running the test suite
====================== ======================
For more details, especially on how to write tests, check out the For more details, especially on how to write tests, check out the
[detailed testing [detailed testing docs][tdocs].
docs](http://zulip.readthedocs.org/en/latest/testing.html).
[tdocs]: http://zulip.readthedocs.org/en/latest/testing.html
To run all the tests, do this: To run all the tests, do this:
``` ```
./tools/test-all ./tools/test-all
``` ```
For the Vagrant environment, you'll want to first enter the environment: For the Vagrant environment, you'll want to first enter the
environment:
``` ```
vagrant ssh vagrant ssh
source /srv/zulip-venv/bin/activate source /srv/zulip-venv/bin/activate
@ -447,5 +487,15 @@ Possible testing issues
above. Afterwards, re-run the `init*-db` and the above. Afterwards, re-run the `init*-db` and the
`do-destroy-rebuild*-database` scripts. `do-destroy-rebuild*-database` scripts.
- When building the development environment using Vagrant and the LXC provider, if you encounter permissions errors, you may need to `chown -R 1000:$(whoami) /path/to/zulip` on the host before running `vagrant up` in order to ensure that the synced directory has the correct owner during provision. This issue will arise if you run `id username` on the host where `username` is the user running Vagrant and the output is anything but 1000. - When building the development environment using Vagrant and the LXC
This seems to be caused by Vagrant behavior; more information can be found [here](https://github.com/fgrehm/vagrant-lxc/wiki/FAQ#help-my-shared-folders-have-the-wrong-owner). provider, if you encounter permissions errors, you may need to
`chown -R 1000:$(whoami) /path/to/zulip` on the host before running
`vagrant up` in order to ensure that the synced directory has the
correct owner during provision. This issue will arise if you run `id
username` on the host where `username` is the user running Vagrant
and the output is anything but 1000.
This seems to be caused by Vagrant behavior; for more information,
see [the vagrant-lxc FAQ entry about shared folder permissions
][lxc-sf].
[lxc-sf]: https://github.com/fgrehm/vagrant-lxc/wiki/FAQ#help-my-shared-folders-have-the-wrong-owner)

58
README.md
View File

@ -38,45 +38,53 @@ Contributing to Zulip
Zulip welcomes all forms of contributions! The page documents the Zulip welcomes all forms of contributions! The page documents the
Zulip development process. Zulip development process.
* **Pull requests**. Before a pull request can be merged, you need to to sign the [Dropbox * **Pull requests**. Before a pull request can be merged, you need to
Contributor License Agreement](https://opensource.dropbox.com/cla/). to sign the [Dropbox Contributor License Agreement][cla]. Also,
Also, please skim our [commit message style please skim our [commit message style guidelines][doc-commit-style].
guidelines](http://zulip.readthedocs.org/en/latest/code-style.html#commit-messages).
* **Testing**. The Zulip automated tests all run automatically when * **Testing**. The Zulip automated tests all run automatically when
you submit a pull request, but you can also run them all in your you submit a pull request, but you can also run them all in your
development environment following the instructions in the [testing development environment following the instructions in the [testing
docs](https://github.com/zulip/zulip/blob/master/README.dev.md#running-the-test-suite). docs][doc-test].
* **Developer Documentation**. Zulip has a growing collection of * **Developer Documentation**. Zulip has a growing collection of
developer documentation on [Read The Docs](https://zulip.readthedocs.org/). developer documentation on [Read The Docs][doc]. Recommended reading
Recommended reading for new contributors includes the for new contributors includes the [directory structure][doc-dirstruct]
[directory structure](http://zulip.readthedocs.org/en/latest/directory-structure.html) and and [new feature tutorial][doc-newfeat].
[new feature tutorial](http://zulip.readthedocs.org/en/latest/new-feature-tutorial.html).
* **Mailing list and bug tracker** Zulip has a [development discussion * **Mailing list and bug tracker** Zulip has a [development discussion
mailing list](https://groups.google.com/forum/#!forum/zulip-devel) and mailing list][gg-devel] and uses [GitHub issues][gh-issues]. Feel
uses [GitHub issues](https://github.com/zulip/zulip/issues). Feel
free to send any questions or suggestions of areas where you'd love to free to send any questions or suggestions of areas where you'd love to
see more documentation to the list! Please report any security issues see more documentation to the list! Please report any security issues
you discover to support@zulip.com. you discover to support@zulip.com.
* **App codebases** This repository is for the Zulip server and web app; the * **App codebases** This repository is for the Zulip server and web
[desktop](https://github.com/zulip/zulip-desktop), app; the [desktop][], [Android][], and [iOS][] apps are separate
[Android](https://github.com/zulip/zulip-android), and
[iOS](https://github.com/zulip/zulip-ios) apps are separate
repositories. repositories.
[cla]: https://opensource.dropbox.com/cla/
[doc]: https://zulip.readthedocs.org/
[doc-commit-style]: http://zulip.readthedocs.org/en/latest/code-style.html#commit-messages
[doc-dirstruct]: http://zulip.readthedocs.org/en/latest/directory-structure.html
[doc-newfeat]: http://zulip.readthedocs.org/en/latest/new-feature-tutorial.html
[doc-test]: https://github.com/zulip/zulip/blob/master/README.dev.md#running-the-test-suite
[gg-devel]: https://groups.google.com/forum/#!forum/zulip-devel
[gh-issues]: https://github.com/zulip/zulip/issues
[desktop]: https://github.com/zulip/zulip-desktop
[android]: https://github.com/zulip/zulip-android
[ios]: https://github.com/zulip/zulip-ios
How to get involved with contributing to Zulip How to get involved with contributing to Zulip
============================================== ==============================================
First, subscribe to the Zulip [development discussion mailing list](https://groups.google.com/forum/#!forum/zulip-devel). First, subscribe to the Zulip [development discussion mailing
list][gg-devel].
The Zulip project uses a system of labels in our [issue The Zulip project uses a system of labels in our [issue
tracker](https://github.com/zulip/zulip/issues) to make it easy to tracker][gh-issues] to make it easy to find a project if you don't
find a project if you don't have your own project idea in mind or want have your own project idea in mind or want to get some experience with
to get some experience with working on Zulip before embarking on a working on Zulip before embarking on a larger project you have in
larger project you have in mind: mind:
* [Bite Size](https://github.com/zulip/zulip/labels/bite%20size): * [Bite Size](https://github.com/zulip/zulip/labels/bite%20size):
Smaller projects that could be a great first contribution. Smaller projects that could be a great first contribution.
@ -90,12 +98,12 @@ larger project you have in mind:
* [Help Wanted](https://github.com/zulip/zulip/labels/help%20wanted): * [Help Wanted](https://github.com/zulip/zulip/labels/help%20wanted):
A broader list of projects that nobody is currently working on. A broader list of projects that nobody is currently working on.
* [Platform support](https://github.com/zulip/zulip/labels/Platform%20support). * [Platform support](https://github.com/zulip/zulip/labels/Platform%20support).
These are open issues about making it possible to install Zulip on a wider These are open issues about making it possible to install Zulip on a
range of platforms. wider range of platforms.
* [Bugs](https://github.com/zulip/zulip/labels/bug). Open bugs. * [Bugs](https://github.com/zulip/zulip/labels/bug): Open bugs.
* [Feature requests](https://github.com/zulip/zulip/labels/enhancement). * [Feature requests](https://github.com/zulip/zulip/labels/enhancement).
Browsing this list can be a great way to find feature ideas to implement that Browsing this list can be a great way to find feature ideas to
other Zulip users are excited about. implement that other Zulip users are excited about.
If you're excited about helping with an open issue, just post on the If you're excited about helping with an open issue, just post on the
conversation thread that you're working on it. You're encouraged to conversation thread that you're working on it. You're encouraged to