mirror of https://github.com/zulip/zulip.git
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
parent
cd2348e9ae
commit
d93a2bcf11
152
README.dev.md
152
README.dev.md
|
|
@ -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
|
||||
version of Vagrant](https://www.vagrantup.com/downloads.html), and
|
||||
then do the following:
|
||||
version of Vagrant][vagrant-dl], and then do the following:
|
||||
```
|
||||
sudo apt-get install lxc lxc-templates cgroup-lite redir
|
||||
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
|
||||
LXC installation
|
||||
instructions](https://github.com/fgrehm/vagrant-lxc) to get Vagrant
|
||||
with LXC for your platform.
|
||||
LXC installation instructions][vagrant-lxc] to get Vagrant with LXC
|
||||
for your platform.
|
||||
|
||||
* If your host is OS X or older Linux, [download VirtualBox](https://www.virtualbox.org/wiki/Downloads),
|
||||
[download Vagrant](https://www.vagrantup.com/downloads.html), and install them both.
|
||||
* If your host is OS X or older Linux, [download VirtualBox][vbox-dl],
|
||||
[download Vagrant][vagrant-dl], and install them both.
|
||||
|
||||
* 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
|
||||
|
|
@ -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
|
||||
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
|
||||
`vagrant up` in your terminal to install the development server. This
|
||||
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
|
||||
lint, management commands, etc., use `vagrant ssh`.
|
||||
|
||||
(A small note on tools/run-dev.py: the `--interface=''` option will make
|
||||
the development server listen on all network interfaces. While this
|
||||
is correct for the Vagrant guest sitting behind a NAT, you probably
|
||||
don't want to use that option when using run-dev.py in other environments).
|
||||
(A small note on tools/run-dev.py: the `--interface=''` option will
|
||||
make the development server listen on all network interfaces. While
|
||||
this is correct for the Vagrant guest sitting behind a NAT, you
|
||||
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
|
||||
|
|
@ -123,7 +129,11 @@ Install the following non-Python dependencies:
|
|||
### 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:
|
||||
sudo apt-get install postgresql-9.1
|
||||
|
|
@ -145,21 +155,26 @@ Now continue with the "All systems" instructions below.
|
|||
|
||||
### 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.
|
||||
|
||||
### 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
|
||||
# user during the install process of CentOS 7).
|
||||
# Add user zulip to the system (not necessary if you configured zulip
|
||||
# as the administrator user during the install process of CentOS 7).
|
||||
useradd zulip
|
||||
|
||||
# Create a password for zulip user
|
||||
|
|
@ -173,13 +188,16 @@ zulip ALL=(ALL) ALL
|
|||
# Switch to zulip user
|
||||
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
|
||||
|
||||
# Install dependencies
|
||||
sudo yum install libffi-devel memcached rabbitmq-server openldap-devel python-devel redis postgresql-server \
|
||||
postgresql-devel postgresql libmemcached-devel wget python-pip openssl-devel freetype-devel libjpeg-turbo-devel \
|
||||
zlib-devel nodejs yuicompressor closure-compiler gettext
|
||||
sudo yum install libffi-devel memcached rabbitmq-server openldap-devel
|
||||
python-devel redis postgresql-server postgresql-devel postgresql \
|
||||
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
|
||||
sudo yum groupinstall "Development Tools"
|
||||
|
|
@ -206,17 +224,21 @@ Now continue with the Common to Fedora/CentOS instructions below.
|
|||
|
||||
### 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
|
||||
cd tsearch_extras
|
||||
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 CXX=eg++
|
||||
|
||||
|
|
@ -224,8 +246,9 @@ export CXX=eg++
|
|||
sudo mkdir /usr/local/share/postgresql/tsearch_data
|
||||
|
||||
|
||||
# Hack around missing dictionary files -- need to fix this to get
|
||||
# the proper dictionaries from what in debian is the hunspell-en-us package.
|
||||
# Hack around missing dictionary files -- need to fix this to get the
|
||||
# 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/en_us.dict
|
||||
sudo touch /usr/local/share/postgresql/tsearch_data/en_us.affix
|
||||
|
|
@ -243,8 +266,9 @@ cd ts2
|
|||
make
|
||||
sudo make install
|
||||
|
||||
# Hack around missing dictionary files -- need to fix this to get
|
||||
# the proper dictionaries from what in debian is the hunspell-en-us package.
|
||||
# Hack around missing dictionary files -- need to fix this to get the
|
||||
# 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/en_us.dict
|
||||
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:
|
||||
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
|
||||
|
||||
# Start the services
|
||||
|
|
@ -291,14 +316,20 @@ To start the development server:
|
|||
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/)
|
||||
* [Understand the architecture](https://docs.docker.com/engine/introduction/understanding-docker/)
|
||||
* [Docker run reference](https://docs.docker.com/engine/reference/run/)
|
||||
* [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 .
|
||||
|
|
@ -316,10 +347,12 @@ docker commit -m "Zulip installed" <container id> user/zulipdev:v2
|
|||
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
|
||||
|
|
@ -335,14 +368,16 @@ docker ps
|
|||
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
|
||||
$ 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
|
||||
|
|
@ -370,10 +405,10 @@ browser window to see changes take effect.
|
|||
|
||||
* 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
|
||||
runserver](https://docs.djangoproject.com/en/1.8/ref/django-admin/#runserver-port-or-address-port),
|
||||
which will automatically restart the Zulip Django and Tornado servers
|
||||
whenever you save changes to Python code. You can watch this happen
|
||||
in the `run-dev.py` console to make sure the backend has reloaded.
|
||||
runserver][django-runserver] which will automatically restart the
|
||||
Zulip Django and Tornado servers whenever you save changes to Python
|
||||
code. You can watch this happen in the `run-dev.py` console to make
|
||||
sure the backend has reloaded.
|
||||
|
||||
* 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
|
||||
|
|
@ -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
|
||||
Django migrations process to create and then run your migrations; see
|
||||
the [new feature
|
||||
tutorial](http://zulip.readthedocs.org/en/latest/new-feature-tutorial.html)
|
||||
for an example. Additionally you should check out the [detailed
|
||||
testing docs](http://zulip.readthedocs.org/en/latest/testing.html) for
|
||||
how to run the tests properly after doing a migration.
|
||||
the [new feature tutorial][new-feature-tutorial] for an example.
|
||||
Additionally you should check out the [detailed testing
|
||||
docs][testing-docs] for how to run the tests properly after doing a
|
||||
migration.
|
||||
|
||||
(In production, everything runs under supervisord and thus will
|
||||
restart if it crashes, and `upgrade-zulip` will take care of running
|
||||
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
|
||||
======================
|
||||
|
||||
For more details, especially on how to write tests, check out the
|
||||
[detailed testing
|
||||
docs](http://zulip.readthedocs.org/en/latest/testing.html).
|
||||
[detailed testing docs][tdocs].
|
||||
|
||||
[tdocs]: http://zulip.readthedocs.org/en/latest/testing.html
|
||||
|
||||
To run all the tests, do this:
|
||||
```
|
||||
./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
|
||||
source /srv/zulip-venv/bin/activate
|
||||
|
|
@ -447,5 +487,15 @@ Possible testing issues
|
|||
above. Afterwards, re-run the `init*-db` and the
|
||||
`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.
|
||||
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).
|
||||
- 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.
|
||||
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
58
README.md
|
|
@ -38,45 +38,53 @@ Contributing to Zulip
|
|||
Zulip welcomes all forms of contributions! The page documents the
|
||||
Zulip development process.
|
||||
|
||||
* **Pull requests**. Before a pull request can be merged, you need to to sign the [Dropbox
|
||||
Contributor License Agreement](https://opensource.dropbox.com/cla/).
|
||||
Also, please skim our [commit message style
|
||||
guidelines](http://zulip.readthedocs.org/en/latest/code-style.html#commit-messages).
|
||||
* **Pull requests**. Before a pull request can be merged, you need to
|
||||
to sign the [Dropbox Contributor License Agreement][cla]. Also,
|
||||
please skim our [commit message style guidelines][doc-commit-style].
|
||||
|
||||
* **Testing**. The Zulip automated tests all run automatically when
|
||||
you submit a pull request, but you can also run them all in your
|
||||
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 on [Read The Docs](https://zulip.readthedocs.org/).
|
||||
Recommended reading for new contributors includes the
|
||||
[directory structure](http://zulip.readthedocs.org/en/latest/directory-structure.html) and
|
||||
[new feature tutorial](http://zulip.readthedocs.org/en/latest/new-feature-tutorial.html).
|
||||
developer documentation on [Read The Docs][doc]. Recommended reading
|
||||
for new contributors includes the [directory structure][doc-dirstruct]
|
||||
and [new feature tutorial][doc-newfeat].
|
||||
|
||||
* **Mailing list and bug tracker** Zulip has a [development discussion
|
||||
mailing list](https://groups.google.com/forum/#!forum/zulip-devel) and
|
||||
uses [GitHub issues](https://github.com/zulip/zulip/issues). Feel
|
||||
mailing list][gg-devel] and uses [GitHub issues][gh-issues]. Feel
|
||||
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
|
||||
you discover to support@zulip.com.
|
||||
|
||||
* **App codebases** This repository is for the Zulip server and web app; the
|
||||
[desktop](https://github.com/zulip/zulip-desktop),
|
||||
[Android](https://github.com/zulip/zulip-android), and
|
||||
[iOS](https://github.com/zulip/zulip-ios) apps are separate
|
||||
* **App codebases** This repository is for the Zulip server and web
|
||||
app; the [desktop][], [Android][], and [iOS][] apps are separate
|
||||
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
|
||||
==============================================
|
||||
|
||||
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
|
||||
tracker](https://github.com/zulip/zulip/issues) to make it easy to
|
||||
find a project if you don't have your own project idea in mind or want
|
||||
to get some experience with working on Zulip before embarking on a
|
||||
larger project you have in mind:
|
||||
tracker][gh-issues] to make it easy to find a project if you don't
|
||||
have your own project idea in mind or want to get some experience with
|
||||
working on Zulip before embarking on a larger project you have in
|
||||
mind:
|
||||
|
||||
* [Bite Size](https://github.com/zulip/zulip/labels/bite%20size):
|
||||
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):
|
||||
A broader list of projects that nobody is currently working on.
|
||||
* [Platform support](https://github.com/zulip/zulip/labels/Platform%20support).
|
||||
These are open issues about making it possible to install Zulip on a wider
|
||||
range of platforms.
|
||||
* [Bugs](https://github.com/zulip/zulip/labels/bug). Open bugs.
|
||||
These are open issues about making it possible to install Zulip on a
|
||||
wider range of platforms.
|
||||
* [Bugs](https://github.com/zulip/zulip/labels/bug): Open bugs.
|
||||
* [Feature requests](https://github.com/zulip/zulip/labels/enhancement).
|
||||
Browsing this list can be a great way to find feature ideas to implement that
|
||||
other Zulip users are excited about.
|
||||
Browsing this list can be a great way to find feature ideas to
|
||||
implement that other Zulip users are excited about.
|
||||
|
||||
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
|
||||
|
|
|
|||
Loading…
Reference in New Issue