paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-10-23 04:52:12 +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
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
While developing, it's helpful to watch the `run-dev.py` console
output, which will show any errors your Zulip development server
encounters.
If you need to work more closely with authentication systems, or if you need
to use the [Zulip REST API][rest-api], which requires an API key, this [detailed doc][authentication-dev-server]
will help you get started.
Here's what you need to do to see your changes take effect:
* The main Django/Tornado server processes are run on top of Django's
[manage.py runserver][django-runserver], which will automatically
restart them when you save changes to Python code they use. You can
watch this happen in the `run-dev.py` console to make sure the backend
has reloaded.
* The Python queue workers will also automatically restart when you
save changes. However, you may need to ctrl-C and then restart
`run-dev.py` manually 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][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.)
To manually query the Postgres database, run `psql zulip` for an
interactive console.
* For changes that don't affect the database model, the Zulip
development environment will automatically detect changes and
restart:
* The main Django/Tornado server processes are run on top of
Django's [manage.py runserver][django-runserver], which will
automatically restart them when you save changes to Python code
they use. You can watch this happen in the `run-dev.py` console
to make sure the backend has reloaded.
* The Python queue workers will also automatically restart when you
save changes. However, you may need to ctrl-C and then restart
`run-dev.py` manually if a queue worker has crashed.
* If you change the database schema (`zerver/models.py`), you'll need
to use the [Django migrations
process](../subsystems/schema-migrations.md) to create and then run
your migrations; see the [new feature
tutorial][new-feature-tutorial] for an example.
* While testing server changes, it's helpful to watch the `run-dev.py`
console output, which will show tracebacks for any 500 errors your
Zulip development server encounters.
* To manually query the Postgres database interactively, use
`./manage.py shell` or `manage.py dbshell` depending whether you
prefer an iPython shell or SQL shell.
* The database(s) used for the automated tests are independent from
the one you use for manual testing in the UI, so changes you make to
the database manually will never affect the automated tests.
## Web
Once the development server is running, you can visit
<http://localhost:9991/> in your browser. By default, the development
server homepage just shows a list of the users that exist on the
server and you can login as any of them by just clicking on a user.
This setup saves time for the common case where you want to test
something other than the login process. To test the login process,
you'll want to change `AUTHENTICATION_BACKENDS` in the not-PRODUCTION
case of `zproject/settings.py` from zproject.backends.DevAuthBackend
to use the auth method(s) you'd like to test.
Here's what you need to do to see your changes take effect:
* If you change CSS files, your changes will appear immediately via hot module
replacement.
* If you change JavaScript or Handlebars templates, the browser
window will be reloaded automatically.
* For Jinja2 backend templates, you'll need to reload the browser manually
to see changes take effect.
Any JavaScript exceptions encountered while using the webapp in a
development environment will be displayed as a large notice.
* Once the development server (`run-dev.py`) is running, you can visit
<http://localhost:9991/> in your browser.
* By default, the development server homepage just shows a list of the
users that exist on the server and you can login as any of them by
just clicking on a user.
* This setup saves time for the common case where you want to test
something other than the login process.
* You can test the login or registration process by clicking the
links for the normal login page.
* If you change CSS files, your changes will appear immediately via
webpack hot module replacement.
* If you change JavaScript code (`static/js`) or Handlebars templates
(`static/templates`), the browser window will be reloaded
automatically.
* For Jinja2 backend templates (`templates/*`), you'll need to reload
the browser manually to see changes take effect.
* Any JavaScript exceptions encountered while using the webapp in a
development environment will be displayed as a large notice, so you
don't need to watch the JavaScript console for exceptions.
## Mobile