Using the development environment
This page describes the basic edit/refresh workflows for working with 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, web app, and mobile apps are below.
If you're working on authentication methods or need to use the Zulip REST API, which requires an API key, see authentication in the development environment.
Common
- Zulip's master branch moves quickly, and you should rebase
constantly with e.g.
git fetch upstream; git rebase upstream/masterto avoid developing on an old version of the Zulip codebase (leading to unnecessary merge conflicts). - Remember to run
tools/provisionto update your development environment after switching branches; it will run in under a second if no changes are required. - After making changes, you'll often want to run the linters and relevant test suites. Consider using our Git pre-commit hook to automatically lint whenever you make a commit.
- 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.
- Many useful development tools, including tools for rebuilding the
database with different test data, are documented in-app at
https://localhost:9991/devtools. - If you want to restore your development environment's database to a
pristine state, you can use
./tools/rebuild-dev-database.
Server
- 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, which will
automatically restart them when you save changes to Python code
they use. You can watch this happen in the
run-dev.pyconsole to make sure the backend has reloaded.
- The main Django/Tornado server processes are run on top of
Django's manage.py runserver, which will
automatically restart them when you save changes to Python code
they use. You can watch this happen in the
- The Python queue workers will also automatically restart when you save changes, as long as they haven't crashed (which can happen if they reloaded into a version with a syntax error).
- If you change the database schema (
zerver/models.py), you'll need to use the Django migrations process; see also the new feature tutorial for an example. - While testing server changes, it's helpful to watch the
run-dev.pyconsole output, which will show tracebacks for any 500 errors your Zulip development server encounters (which are probably caused by bugs in your code). - To manually query Zulip's database interactively, use
./manage.py shellormanage.py dbshell. - 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 (
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 log in 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.
- Most changes will take effect automatically. Details:
- 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 window to see your changes. - Any JavaScript exceptions encountered while using the web app in a development environment will be displayed as a large notice, so you don't need to watch the JavaScript console for exceptions.
- Both Chrome and Firefox have great debuggers, inspectors, and profilers in their built-in developer tools.
debug.jshas some occasionally useful JavaScript profiling code.
Mobile
See the mobile project's documentation on using a development server for mobile development.