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

88 lines
3.3 KiB
Markdown
Raw Normal View History

dev-overview: Improve organization of installation overview page. Fixes #1814. [substantially tweaked by tabbott]
2016-09-21 19:31:51 +02:00
# Development environment installation
Move development installations instructions to a separate file. This will make the core README.md file cleaner.
2015-11-04 05:57:54 +01:00
Simplify dev env setup overview.
2016-11-28 01:56:24 +01:00
## Requirements
dev-overview: Document cloud server option.
2016-10-11 02:10:39 +02:00
docs: Change dev -> development everywhere.
2016-11-29 23:23:54 +01:00
The Zulip development environment can be installed on **macOS,
docs: Update development environment docs for Ubuntu bionic. We also clean up some flows in the documentation that were somewhat confusing that I noticed while working on this.
2018-05-30 18:42:03 +02:00
Windows, and Linux** (Debian or Ubuntu recommended). You'll need at least **2GB
docs: Change dev -> development everywhere.
2016-11-29 23:23:54 +01:00
of available RAM**.
dev-overview: Document cloud server option.
2016-10-11 02:10:39 +02:00
docs: Change dev -> development everywhere.
2016-11-29 23:23:54 +01:00
Installing the Zulip development environment requires downloading several hundred
Simplify dev env setup overview.
2016-11-28 01:56:24 +01:00
megabytes of dependencies, so you will need an **active, reasonably fast,
internet connection throughout the entire installation processes.** You can
[configure a proxy][configure-proxy] if you need one.
dev-overview: Improve organization of installation overview page. Fixes #1814. [substantially tweaked by tabbott]
2016-09-21 19:31:51 +02:00
docs: Separate recommend and vagrant setup sections for dev setup. This will possibly direct more users towards WSL setup on Windows.
2021-11-15 05:21:40 +01:00
## Recommended setup
Move development installations instructions to a separate file. This will make the core README.md file cleaner.
2015-11-04 05:57:54 +01:00
docs: Update development environment docs for Ubuntu bionic. We also clean up some flows in the documentation that were somewhat confusing that I noticed while working on this.
2018-05-30 18:42:03 +02:00
**For first-time contributors, we recommend using the
docs: Separate recommend and vagrant setup sections for dev setup. This will possibly direct more users towards WSL setup on Windows.
2021-11-15 05:21:40 +01:00
[Vagrant development environment][install-vagrant]** on
macOS and Linux based OS and [WSL 2 setup][install-via-wsl] on Windows.
dev-overview: Improve organization of installation overview page. Fixes #1814. [substantially tweaked by tabbott]
2016-09-21 19:31:51 +02:00
docs: Separate recommend and vagrant setup sections for dev setup. This will possibly direct more users towards WSL setup on Windows.
2021-11-15 05:21:40 +01:00
## Vagrant setup
[Vagrant setup][install-vagrant] creates a virtual machine (for Windows and macOS) or a
docs: Update development environment docs for Ubuntu bionic. We also clean up some flows in the documentation that were somewhat confusing that I noticed while working on this.
2018-05-30 18:42:03 +02:00
Linux container (otherwise) inside which the Zulip server and all
related services will run. Vagrant adds a bit of overhead to using the
Zulip development server, but provides an isolated environment that is
easy to install, update, and uninstall. It has been well-tested and
performs well.
dev-overview: Improve organization of installation overview page. Fixes #1814. [substantially tweaked by tabbott]
2016-09-21 19:31:51 +02:00
docs: Delete manual development installation documentation. This documentation does not work and has not been used for years. At this point, `provision` is sufficiently flexible in terms of supporting different platforms that any future work will be to extend it, rather than maintaining awkward manual installation documentation.
2021-04-14 06:23:26 +02:00
## Advanced setup
dev-overview: Improve organization of installation overview page. Fixes #1814. [substantially tweaked by tabbott]
2016-09-21 19:31:51 +02:00
docs: Update development environment docs for Ubuntu bionic. We also clean up some flows in the documentation that were somewhat confusing that I noticed while working on this.
2018-05-30 18:42:03 +02:00
Zulip also supports a wide range of ways to install the Zulip
development environment:
dev-overview: Improve organization of installation overview page. Fixes #1814. [substantially tweaked by tabbott]
2016-09-21 19:31:51 +02:00
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- On Linux platforms, you can **[install directly][install-direct]**.
- On Windows, you can **[install directly][install-via-wsl]** via WSL 2.
Simplify dev env setup overview.
2016-11-28 01:56:24 +01:00
## Slow internet connections
docs: Update development environment docs for Ubuntu bionic. We also clean up some flows in the documentation that were somewhat confusing that I noticed while working on this.
2018-05-30 18:42:03 +02:00
If you have a very slow network connection, however, you may want to
avoid using Vagrant (which involves downloading an Ubuntu virtual
docs: Delete manual development installation documentation. This documentation does not work and has not been used for years. At this point, `provision` is sufficiently flexible in terms of supporting different platforms that any future work will be to extend it, rather than maintaining awkward manual installation documentation.
2021-04-14 06:23:26 +02:00
machine or Linux container) and [install directly][install-direct] on
a Linux system.
Simplify dev env setup overview.
2016-11-28 01:56:24 +01:00
docs: Update development environment docs for Ubuntu bionic. We also clean up some flows in the documentation that were somewhat confusing that I noticed while working on this.
2018-05-30 18:42:03 +02:00
An alternative option if you have poor network connectivity is to rent
a cloud server and install the Zulip development environment for
remote use. See the [next section][self-install-remote] for details.
Simplify dev env setup overview.
2016-11-28 01:56:24 +01:00
## Installing remotely
docs: Change dev -> development everywhere.
2016-11-29 23:23:54 +01:00
The Zulip development environment works well on remote virtual
machines. This can be a good alternative for those with poor network
connectivity or who have limited storage/memory on their local
machines.
Simplify dev env setup overview.
2016-11-28 01:56:24 +01:00
docs: Update development environment docs for Ubuntu bionic. We also clean up some flows in the documentation that were somewhat confusing that I noticed while working on this.
2018-05-30 18:42:03 +02:00
We recommend giving the Zulip development environment its **own
virtual machine**, running one of
[the supported platforms for direct installation][install-direct],
with at least **2GB of memory**.
Simplify dev env setup overview.
2016-11-28 01:56:24 +01:00
docs: Change dev -> development everywhere.
2016-11-29 23:23:54 +01:00
If the Zulip development environment will be the only thing running on
the remote virtual machine, we recommend installing
[directly][install-direct]. Otherwise, we recommend the
[Vagrant][install-vagrant] method so you can easily uninstall if you
need to.
Simplify dev env setup overview.
2016-11-28 01:56:24 +01:00
## Next steps
dev-overview: Improve organization of installation overview page. Fixes #1814. [substantially tweaked by tabbott]
2016-09-21 19:31:51 +02:00
Once you've installed the Zulip development environment, you'll want
to read these documents to learn how to use it:
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- [Using the development environment][using-dev-env]
- [Testing][testing] (and [Configuring CI][ci])
Simplify dev env setup overview.
2016-11-28 01:56:24 +01:00
docs: Correct “setup” as a verb to “set up”. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-08-11 01:47:54 +02:00
And if you've set up the Zulip development environment on a remote
docs: Change dev -> development everywhere.
2016-11-29 23:23:54 +01:00
machine, take a look at our tips for
[developing remotely][dev-remote].
Improve first-time contributor docs. Fixes #747. Fixes #748. This updates README.dev.md to include clear, step-by-step instructions for setting up the Zulip dev environment Windows 10, OS X El Capitan, Ubuntu 14.04 Trusty, and Ubuntu 16.04 Xenial. It is aimed at first-time contributors. I tested these instructions multiple times on each of the target systems. Also added is a "trobleshooting and common errors" section which documents the most common errors contributors are likely to encounter during setup and how to fix them. Improvements based on feedback from @timabbott. - Fixes whitespace issues so linter will pass. - Updates memory requirement. - Re-orders so operating systems are listed alphabetically. - Updates headings to be clearer. - Updates and adds ToC entries for clarity. - Adds screen shot of Zulip dev environment running in browser. - Adds details about using dev environment, including about logging. - Misc other minor changes for clarity. - Adds a stub for docs/logging.md - Adds details about configuring Cygwin for native symlinks.
2016-05-05 01:16:31 +02:00
docs: Reduce the number of apparently broken links on github. - Updated 260+ links from ".html" to ".md" to reduce the number of issues reported about hyperlinks not working when viewing docs on Github. - Removed temporary workaround that suppressed all warnings reported by sphinx build for every link ending in ".html". Details: The recent upgrade to recommonmark==0.5.0 supports auto-converting ".md" links to ".html" so that the resulting HTML output is correct. Notice that links pointing to a heading i.e. "../filename.html#heading", were not updated because recommonmark does not auto-convert them. These links do not generate build warnings and do not cause any issues. However, there are about ~100 such links that might still get misreported as broken links. This will be a follow-up issue. Background: docs: pip upgrade recommonmark and CommonMark #13013 docs: Allow .md links between doc pages #11719 Fixes #11087.
2019-09-30 19:37:56 +02:00
[dev-remote]: remote.md
docs: Convert .html#fragment links to .md#fragment. This uses the myst_heading_anchors option to automatically generate header anchors and make Sphinx aware of them. See https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#auto-generated-header-anchors. Note: to be compatible with GitHub, MyST-Parser uses a slightly different convention for .md fragment links than .html fragment links when punctuation is involved. This does not affect the generated fragment links in the HTML output. Fixes #13264. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2022-02-16 01:39:15 +01:00
[install-direct]: setup-advanced.md#installing-directly-on-ubuntu-debian-centos-or-fedora
docs: Clean redundant relative links. We previously had a convention of redundantly including the directory in relative links to reduce mistakes when moving content from one file to another. However, these days we have a broken link checker in test-documentation, and after #21237, MyST-Parser will check relative links (including fragments) when you run build-docs. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2022-02-24 00:17:21 +01:00
[install-vagrant]: setup-vagrant.md
Simplify dev env setup overview.
2016-11-28 01:56:24 +01:00
[self-install-remote]: #installing-remotely
[self-slow-internet]: #slow-internet-connections
docs: Convert .html#fragment links to .md#fragment. This uses the myst_heading_anchors option to automatically generate header anchors and make Sphinx aware of them. See https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#auto-generated-header-anchors. Note: to be compatible with GitHub, MyST-Parser uses a slightly different convention for .md fragment links than .html fragment links when punctuation is involved. This does not affect the generated fragment links in the HTML output. Fixes #13264. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2022-02-16 01:39:15 +01:00
[configure-proxy]: setup-vagrant.md#specifying-a-proxy
docs: Reduce the number of apparently broken links on github. - Updated 260+ links from ".html" to ".md" to reduce the number of issues reported about hyperlinks not working when viewing docs on Github. - Removed temporary workaround that suppressed all warnings reported by sphinx build for every link ending in ".html". Details: The recent upgrade to recommonmark==0.5.0 supports auto-converting ".md" links to ".html" so that the resulting HTML output is correct. Notice that links pointing to a heading i.e. "../filename.html#heading", were not updated because recommonmark does not auto-convert them. These links do not generate build warnings and do not cause any issues. However, there are about ~100 such links that might still get misreported as broken links. This will be a follow-up issue. Background: docs: pip upgrade recommonmark and CommonMark #13013 docs: Allow .md links between doc pages #11719 Fixes #11087.
2019-09-30 19:37:56 +02:00
[using-dev-env]: using.md
[testing]: ../testing/testing.md
docs: Convert .html#fragment links to .md#fragment. This uses the myst_heading_anchors option to automatically generate header anchors and make Sphinx aware of them. See https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#auto-generated-header-anchors. Note: to be compatible with GitHub, MyST-Parser uses a slightly different convention for .md fragment links than .html fragment links when punctuation is involved. This does not affect the generated fragment links in the HTML output. Fixes #13264. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2022-02-16 01:39:15 +01:00
[ci]: ../git/cloning.md#step-3-configure-continuous-integration-for-your-fork
[install-via-wsl]: setup-advanced.md#installing-directly-on-windows-10-with-wsl-2