paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-10-25 00:53:56 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Rewrite the guide on using the development environment.

Browse Source 
This correct various inaccuracies and adds a bulleted list structure
for better clarity.

I think there's a lot more that could be done here in the form of
linking to other pages, discussing restarting `run-dev.py`, etc.
This commit is contained in:
Tim Abbott
2020-01-16 15:56:39 -08:00
parent b3901c830b
commit c113d74daf
1 changed files with 62 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

117
docs/development/using.md
View File

@@ -2,67 +2,74 @@ Using the Development Environment
================================= =================================
This page describes the basic edit/refresh workflows for working with This page describes the basic edit/refresh workflows for working with
the Zulip development environment. the Zulip development environment. Generally, the development
environment will automatically update as soon as you save changes
using your editor. Details for work on the [server](#server),
[webapp](#web), and [mobile apps](#mobile) are below.
If you're working on authentication methods or need to use the [Zulip
REST API][rest-api], which requires an API key, see [authentication in
the development environment][authentication-dev-server].
## Common (linting and testing)
* After making changes, you'll often want to run the
[linters](../testing/linters.md) and relevant [test
suites](../testing/testing.md). All of our test suites are designed
to support quickly testing just a single file or test case, which
you should take advantage of to save time. Consider using our [Git
pre-commit hook](../git/zulip-tools.html#set-up-git-repo-script) to
automatically lint changes when you commit them.
## Server ## Server
While developing, it's helpful to watch the `run-dev.py` console * For changes that don't affect the database model, the Zulip
output, which will show any errors your Zulip development server development environment will automatically detect changes and
encounters. restart:
* The main Django/Tornado server processes are run on top of
If you need to work more closely with authentication systems, or if you need Django's [manage.py runserver][django-runserver], which will
to use the [Zulip REST API][rest-api], which requires an API key, this [detailed doc][authentication-dev-server] automatically restart them when you save changes to Python code
will help you get started. they use. You can watch this happen in the `run-dev.py` console
to make sure the backend has reloaded.
Here's what you need to do to see your changes take effect: * The Python queue workers will also automatically restart when you
save changes. However, you may need to ctrl-C and then restart
* The main Django/Tornado server processes are run on top of Django's `run-dev.py` manually if a queue worker has crashed.
[manage.py runserver][django-runserver], which will automatically * If you change the database schema (`zerver/models.py`), you'll need
restart them when you save changes to Python code they use. You can to use the [Django migrations
watch this happen in the `run-dev.py` console to make sure the backend process](../subsystems/schema-migrations.md) to create and then run
has reloaded. your migrations; see the [new feature
tutorial][new-feature-tutorial] for an example.
* The Python queue workers will also automatically restart when you * While testing server changes, it's helpful to watch the `run-dev.py`
save changes. However, you may need to ctrl-C and then restart console output, which will show tracebacks for any 500 errors your
`run-dev.py` manually if a queue worker has crashed. Zulip development server encounters.
* To manually query the Postgres database interactively, use
* If you change the database schema, you'll need to use the standard `./manage.py shell` or `manage.py dbshell` depending whether you
Django migrations process to create and then run your migrations; see prefer an iPython shell or SQL shell.
the [new feature tutorial][new-feature-tutorial] for an example. * The database(s) used for the automated tests are independent from
Additionally, you should check out the [detailed testing the one you use for manual testing in the UI, so changes you make to
docs][testing-docs] for how to run the tests properly after doing a the database manually will never affect the automated tests.
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.)
To manually query the Postgres database, run `psql zulip` for an
interactive console.
## Web ## Web
Once the development server is running, you can visit * Once the development server (`run-dev.py`) is running, you can visit
<http://localhost:9991/> in your browser. By default, the development <http://localhost:9991/> in your browser.
server homepage just shows a list of the users that exist on the * By default, the development server homepage just shows a list of the
server and you can login as any of them by just clicking on a user. users that exist on the server and you can login as any of them by
This setup saves time for the common case where you want to test just clicking on a user.
something other than the login process. To test the login process, * This setup saves time for the common case where you want to test
you'll want to change `AUTHENTICATION_BACKENDS` in the not-PRODUCTION something other than the login process.
case of `zproject/settings.py` from zproject.backends.DevAuthBackend * You can test the login or registration process by clicking the
to use the auth method(s) you'd like to test. links for the normal login page.
* If you change CSS files, your changes will appear immediately via
Here's what you need to do to see your changes take effect: webpack hot module replacement.
* If you change JavaScript code (`static/js`) or Handlebars templates
* If you change CSS files, your changes will appear immediately via hot module (`static/templates`), the browser window will be reloaded
replacement. automatically.
* If you change JavaScript or Handlebars templates, the browser * For Jinja2 backend templates (`templates/*`), you'll need to reload
window will be reloaded automatically. the browser manually to see changes take effect.
* For Jinja2 backend templates, you'll need to reload the browser manually * Any JavaScript exceptions encountered while using the webapp in a
to see changes take effect. development environment will be displayed as a large notice, so you
don't need to watch the JavaScript console for exceptions.
Any JavaScript exceptions encountered while using the webapp in a
development environment will be displayed as a large notice.
## Mobile ## Mobile